# List models

> GET /models のリファレンスです。ゲートウェイが返すモデルオブジェクト、一覧に含まれない情報、カタログが空のときのフォールバック、エラー、サンプルを説明します。

Source: https://kiln.bricksum.com/docs/ja/api-reference/models

`GET https://api.bricksum.com/v1/models`

ゲートウェイが現在提供できるモデル ID を、OpenAI のモデル一覧形式で返します。一覧はモデルサーバーではなく、ゲートウェイのカタログから作られます。各項目には model フィールドに指定する ID が入ります。単価、コンテキスト長、対応機能はこのレスポンスには含まれません。

モデルごとの単価、コンテキスト長、対応機能は [モデル](https://kiln.bricksum.com/docs/ja/models) ページにあります。

## 認証

ゲートウェイが処理するエンドポイントの認証方法はすべて同じで、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページで説明しています。

## リクエスト

| ステータス | 説明 |
| --- | --- |
| 対応 | ゲートウェイが処理するか、公開済みの実測で動作を確認した項目です。 |
| 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| 無視 | 200 で受け付けられますが、適用されません。レスポンスのその他の部分は通常どおりです。 |
| 非対応 | エラーで拒否されるか、説明に記載したモデルでは動作しません。 |

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `query string` | string |  |  | 無視 | このエンドポイントはパラメータを受け取りません。クエリ文字列は受け付けられますが、レスポンスには影響しません。レスポンスボディで説明するフォールバックでは、モデルサーバーに転送されません。 |
| `request body` | none |  |  | 無視 | GET リクエストにボディを付けても読み取りません。ボディなしでリクエストしてください。 |

結果を変えるのは認証ヘッダーだけで、すべてのエンドポイントが受け取るものと同じです。ほかに送るものはありません。

## レスポンスボディ

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `object` | string | "list" という固定値です。 |
| `data[].id` | string | モデル ID です（例：qwen3-32b）。推論リクエストの model フィールドにこの値を指定します。 |
| `data[].object` | string | "model" という固定値です。 |
| `data[].created` | integer | Unix 秒の時刻で、ゲートウェイがレスポンスを組み立てる時点で付与します。1 回のレスポンス内のすべての項目が同じ値を持ち、呼び出しごとに値が変わります。モデルが追加された時刻を表すものではありません。 |
| `data[].owned_by` | string | "bricksum" という固定値です。 |

## エラー

このエンドポイントのエラーは、OpenAI の形式（{"error": {"message", "type", "param", "code"}}）で返されます。error.code の欄が空の行は、リクエストがエンドポイントに届く前にゲートウェイが返すエラーで、表の下に示すボディ形式を使用します。

| ステータス | error.code | 原因 | 対処 |
| --- | --- | --- | --- |
| 405 | `method_not_allowed` | メソッドが GET ではありません。 | GET でリクエストしてください。レスポンスには Allow: GET ヘッダーが付きます。 |
| 502 |  | フォールバック時のみ発生します。カタログが空で、モデルサーバーに到達できなかった場合です。ボディは JSON ではなく、プレーンテキストの upstream error です。 | 少し待ってから再試行してください。 |
| 503 |  | フォールバック時のみ発生します。カタログが空で、選択できるモデルサーバーがない場合です。ボディは JSON ではなく、プレーンテキストの no upstream available です。 | 少し待ってから再試行し、ステータスページを確認してください。 |

401、402、403、429 は、リクエストがこのエンドポイントに届く前にゲートウェイが返します。これらは [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページに一度だけ記載しています。

認証、クレジット、予算、レート制限（1 分あたりのリクエスト数、トークン数）のエラーは、リクエストがこのエンドポイントに届く前にゲートウェイが返します。ボディには error.code ではなく error.type が入ります。

```json
{
  "error": {
    "message": "invalid API key",
    "type": "authorization"
  }
}
```

すべてのステータスコードは [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにあります。

## 制限

- 課金：課金されません。ゲートウェイはこのエンドポイントの usage イベントを発行せず、レスポンスに X-Neocloud-Generation-Id ヘッダーはありません。
- 一覧の内容：ゲートウェイが提供するモデルだけが含まれます。廃止予定のモデルと準備中のモデルは含まれないため、ここにない ID は推論エンドポイントで 404（model_not_found）として拒否されます。
- 空のカタログ：ゲートウェイが提供可能なモデルを 1 つも把握できない場合、リクエストをモデルサーバーにプロキシし、そのサーバーのレスポンスをそのまま返します。このときのボディの ID はモデルサーバーのものなので、ゲートウェイが提供する ID と異なることがあります。
- 単体取得は提供していません：GET /models/{model} は提供されていません。ゲートウェイがそのパスをハンドラーのないサービスへ送るため、エラーオブジェクトではなくプレーンテキストの 404 が返ります。個々のモデルは上記の一覧から読み取ってください。

429 のヘッダーと再試行の方法は [レート制限](https://kiln.bricksum.com/docs/ja/rate-limits) ページにあります。

## サンプル

### リクエスト

**cURL**
```bash
curl https://api.bricksum.com/v1/models \
  -H "Authorization: Bearer $KILN_API_KEY"
```

**Python**
```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bricksum.com/v1",
    api_key=os.environ["KILN_API_KEY"],
)

for model in client.models.list():
    print(model.id)
```

**JavaScript**
```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bricksum.com/v1",
  apiKey: process.env.KILN_API_KEY,
});

const list = await client.models.list();
for (const model of list.data) console.log(model.id);
```

### レスポンス

**200 OK**
```json
{
  "object": "list",
  "data": [
    {
      "id": "qwen3-32b",
      "object": "model",
      "created": 1710000000,
      "owned_by": "bricksum"
    }
  ]
}
```

**405 Method Not Allowed**
```json
{
  "error": {
    "message": "Method POST is not allowed on /v1/models (use GET).",
    "type": "invalid_request_error",
    "param": "",
    "code": "method_not_allowed"
  }
}
```