# Chat completions

> POST /chat/completions のリファレンスです。リクエストパラメータごとの対応状況、レスポンスとストリームチャンクのフィールド、エラー、制限、サンプルを説明します。

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

`POST https://api.bricksum.com/v1/chat/completions`

会話に対するモデルの応答を生成します。リクエストとレスポンスは OpenAI Chat Completions 形式に従います。以下の各パラメータには、現在ゲートウェイがその値をどう扱うかを示しています。

## 認証

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

## リクエストボディ

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

### 共通パラメータ

以下のパラメータの定義は [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページに一度だけ記載しています。ここには、このエンドポイントで異なる点だけを記載します。

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `model` | string | 必須 |  | 対応 | 共通の定義と同じです。 |
| `messages` | array | 必須 |  | 対応 | 配列が空または未指定の場合は 400（empty_array）で拒否されます。メッセージは role と content で構成され、形は以下のとおりです。 |
| `messages[].role (system メッセージ)` | string | 必須 |  | 対応 | "system" を指定します。 指定できる値: system |
| `messages[].content (system メッセージ)` | string | 必須 |  | 対応 | 会話全体に適用する指示です。 |
| `messages[].role (user メッセージ)` | string | 必須 |  | 対応 | "user" を指定します。 指定できる値: user |
| `messages[].content (user メッセージ)` | string \| array | 必須 |  | 対応 | テキスト、または content パートの配列です。ゲートウェイはパート配列を変更せずに転送します。画像パート（image_url）は画像入力に対応するモデルでのみ動作します。モデルページを確認してください。 |
| `messages[].role (assistant メッセージ)` | string | 必須 |  | 対応 | "assistant" を指定します。 指定できる値: assistant |
| `messages[].content (assistant メッセージ)` | string \| null |  |  | 対応 | 以前のモデルの応答です。応答がツール呼び出しだった場合は null にできます。 |
| `messages[].tool_calls (assistant メッセージ)` | array |  |  | 対応 | モデルが返した tool_calls 配列です。対応する tool メッセージの前に、変更せずに送り返します。 |
| `messages[].role (tool メッセージ)` | string | 必須 |  | 対応 | "tool" を指定します。 指定できる値: tool |
| `messages[].tool_call_id (tool メッセージ)` | string | 必須 |  | 対応 | この結果が対応するツール呼び出しの id です。 |
| `messages[].content (tool メッセージ)` | string | 必須 |  | 対応 | ツールの実行結果です。通常は JSON 文字列です。 |
| `max_tokens` | integer |  |  | 対応 | 送信した値のままモデルサーバーに渡されます。この上限で生成が止まると（finish_reason: "length"）、非ストリーミングのレスポンスで content が空になることがあります。 |
| `stream` | boolean |  | `false` | 対応 | ゲートウェイは文字列 "true" と数値 1 も true として読み取り、転送前にこのフィールドを boolean に書き換えます。 |
| `tools` | array |  |  | 対応 | OpenAI の function 定義の形式で送信します。 |
| `tools[].type` | string | 必須 |  | 対応 | "function" を指定します。 指定できる値: function |
| `tools[].function.name` | string | 必須 |  | 対応 | モデルが tool_calls で使用する名前です。 |
| `tools[].function.description` | string | 必須 |  | 対応 | 関数の動作の説明です。description のない関数は 400 で拒否されます。 |
| `tools[].function.parameters` | object |  |  | 対応 | 関数の引数の JSON Schema です。 |
| `tool_choice = "auto"` | string |  |  | 対応 | 文字列 "auto" として送信します。 |
| `tool_choice = "required" \| {"type": "function", ...}` | string \| object |  |  | 非対応 | 強制的なツール選択です。"required" または関数名を指定して送信します。qwen3-32b では、強制的なツール選択が明確なエラーなしに失敗します（2026-09-26 実測）。tool_choice を "required" にすると本文が平文 "Internal Server Error" の HTTP 500 が返り、関数を指定すると arguments が空の 200（finish_reason "stop"）が返ります。どちらも 4xx ではないため、再試行では解決しません。tool_choice は "auto" のみを送ってください。 |

### このエンドポイント固有のパラメータ

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `stream_options` | object |  |  | 対応 | ストリーミングレスポンスのオプションです。stream: true と一緒に送る場合にのみ使用してください。 |
| `stream_options.include_usage` | boolean |  | `false` | 対応 | true の場合、ストリームの最後に、choices が空で usage オブジェクトにトークン数と cost を含むチャンクが 1 つ追加されます。ゲートウェイはトークン計測のためにすべてのストリーミングリクエストでこの値を設定し、指定がなかった場合は usage チャンクを取り除きます。 |
| `parallel_tool_calls` | boolean |  |  | 非対応 | モデルページで並列ツール呼び出しが対応となっているモデルでのみ適用され、qwen3-32b は該当しません。gpt-oss-120b での実測では、リクエストは 200 で受け付けられ、モデルは応答ごとに最大 1 つのツールだけを呼び出しました。qwen3-32b では parallel_tool_calls の設定が適用されません。これは応答のツール呼び出しが 1 つだけという意味ではありません。parallel_tool_calls: false を送っても、1 つの応答に複数のツール呼び出しが含まれることがあります。tool_calls のすべての項目に、それぞれ tool メッセージで応答してください。 |
| `reasoning_effort` | string |  |  | 対応 | 送信した値のままモデルに渡されます。gpt-oss-120b は low、medium、high を受け付けます。他のモデルがこの値に従うかは公開されていません。値が高いほど reasoning トークンを多く使うため、レイテンシと出力トークンが増えます。 指定できる値: low, medium, high |
| `temperature` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: 0–2 |
| `top_p` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: 0–1 |
| `n` | integer |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `seed` | integer |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `presence_penalty` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: -2–2 |
| `frequency_penalty` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: -2–2 |
| `stop` | string \| array |  |  | 無視 | 受け付けられますが、適用されません。stop 文字列の後も生成が続きます。 |
| `response_format` | object |  |  | 非対応 | json_object と json_schema はまだ動作しません。リクエストは 200 で受け付けられますが、content が空で返されます。JSON が必要な場合は、プロンプトで JSON のみで回答するよう指示し、クライアント側で結果をパースして検証してください。 |
| `ignore_eos` | boolean |  |  | 非対応 | gpt-oss モデルで true を送ると、モデルに届く前に 400（unsupported_parameter）で拒否されます。他のモデルではモデルサーバーに転送されます。 |

ここに記載のない OpenAI chat パラメータも、同じようにモデルサーバーに転送されます。Kiln は動作を検証していません。

## レスポンスボディ

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `id` | string | chat completion の ID です。 |
| `object` | string | "chat.completion" です。 |
| `created` | integer | 作成時刻（Unix 秒）です。 |
| `model` | string | 応答を生成したモデル ID です。 |
| `choices[].index` | integer | choice の位置です。 |
| `choices[].message.role` | string | "assistant" です。 |
| `choices[].message.content` | string \| null | 生成されたテキストです。finish_reason が "length" の場合は空になることがあり、応答がツール呼び出しの場合は null になることがあります。 |
| `choices[].message.tool_calls` | array | モデルが実行を求めるツール呼び出しです。id、type、function.name と、JSON 文字列の function.arguments を含みます。 |
| `choices[].finish_reason` | string | "stop"、"length"（max_tokens による打ち切り）、"tool_calls" のいずれかです。 |
| `usage.prompt_tokens` | integer | 入力トークン数です。 |
| `usage.completion_tokens` | integer | 出力トークン数です。reasoning トークンを含みます。 |
| `usage.total_tokens` | integer | 入力と出力のトークン数の合計です。 |
| `usage.prompt_tokens_details.cached_tokens` | integer | プレフィックスキャッシュから処理された入力トークン数です。モデルサーバーが報告した場合にのみ含まれます。 |
| `usage.cost` | number | このリクエストでクレジットから差し引かれる金額（USD）です。ゲートウェイが追加します。 |
| `X-Neocloud-Generation-Id` | header | このリクエストの usage イベント ID を含むレスポンスヘッダーです。ログと一緒に保存してください。 |

## ストリームチャンク

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `object` | string | "chat.completion.chunk" です。 |
| `choices[].delta.content` | string | このチャンクで新しく生成されたテキストです。 |
| `choices[].delta.tool_calls` | array | ツール呼び出しの断片です。function.arguments を index ごとに連結してください。 |
| `choices[].finish_reason` | string \| null | 最後の content チャンクまでは null で、最後のチャンクに終了理由が入ります。 |
| `usage` | object | stream_options.include_usage が true の場合にのみ、最後のチャンクに含まれます。このチャンクの choices 配列は空です。 |
| `usage.cost` | number | このリクエストでクレジットから差し引かれる金額（USD）です。ゲートウェイが usage チャンクに追加します。 |

stream: true の場合、各 data: 行に以下のフィールドを持つチャンクが 1 つずつ入ります。keepalive コメント、data: [DONE]、切断時の動作は [ストリーミング](https://kiln.bricksum.com/docs/ja/streaming) ページで説明しています。

## エラー

| ステータス | error.code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | `empty_array` | messages が空または未指定です。 | メッセージを 1 件以上送信してください。 |
| 400 | `unsupported_parameter` | gpt-oss モデルに ignore_eos: true を送信しました。 | ignore_eos を削除してください。 |
| 400 |  | モデルサーバーがリクエストを拒否しました。不正な JSON、無効なパラメータ、description のない関数、モデルページに記載のモデル別コンテキスト長を超えるコンテキストが原因です。 | リクエスト内容を修正してください。そのまま再試行しないでください。 |
| 404 | `model_not_found` | モデル ID がカタログにありません。 | GET /models で ID を確認してください。 |
| 429 | `rate_limit_exceeded` | 組織ですでに 8 件のリクエストが処理中です。レート制限ヘッダーは付きません。 | 指数バックオフで再試行してください。 |
| 502 |  | モデルバックエンドがエラーを返したか、到達できませんでした。ボディはプレーンテキストです。 | 指数バックオフで再試行してください。 |
| 503 |  | サービスがメンテナンス中か、利用可能なモデルバックエンドがありません。 | メンテナンス中は Retry-After の日時まで待ってください。それ以外は指数バックオフで再試行してください。 |

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

メッセージの文言ではなく、HTTP ステータスと error.code で分岐してください。error.code の欄が空の場合、ボディに code はありません。すべてのステータスコードは [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにあります。

## 制限

コンテキスト長、リクエストボディのサイズ、タイムアウト、組織ごとのレート制限もここに適用され、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページに一度だけ記載しています。

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

## サンプル

### リクエスト

**cURL**
```bash
curl https://api.bricksum.com/v1/chat/completions \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "messages": [
      {"role": "system", "content": "Answer briefly."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 800
  }'
```

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

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

resp = client.chat.completions.create(
    model="qwen3-32b",
    messages=[
        {"role": "system", "content": "Answer briefly."},
        {"role": "user", "content": "Hello!"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)
print(resp.usage)
```

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

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

const resp = await client.chat.completions.create({
  model: "qwen3-32b",
  messages: [
    { role: "system", content: "Answer briefly." },
    { role: "user", content: "Hello!" },
  ],
  max_tokens: 800,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);
```

### レスポンス

**200 OK**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}
```

**text/event-stream**
```text
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21,"cost":0.000001155}}

data: [DONE]
```

**400 Bad Request**
```json
{
  "error": {
    "message": "Invalid 'messages': the array must contain at least one message.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "empty_array"
  }
}
```