Chat completions

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

POST/chat/completions

URL

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

リクエスト

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

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

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

{
  "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
  }
}

200 OK · text/event-stream

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

{
  "error": {
    "message": "Invalid 'messages': the array must contain at least one message.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "empty_array"
  }
}

この例のトークン数と cost は gpt-oss-120b で測定した例示の値で、qwen3-32b の値ではありません。

認証

ゲートウェイが処理するエンドポイントの認証方法はすべて同じで、 API リファレンスページで説明しています。

リクエストボディ

対応状況

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

共通パラメータ

以下のパラメータの定義は API リファレンスページに一度だけ記載しています。ここには、このエンドポイントで異なる点だけを記載します。

modelstring必須対応
共通の定義と同じです。
完全な定義を見る
messagesarray必須対応
配列が空または未指定の場合は 400（empty_array）で拒否されます。メッセージは role と content で構成され、形は以下のとおりです。
完全な定義を見る
system メッセージ
- rolestring必須対応
  "system" を指定します。
  指定できる値
  system
- contentstring必須対応
  会話全体に適用する指示です。
user メッセージ
- rolestring必須対応
  "user" を指定します。
  指定できる値
  user
- contentstring | array必須対応
  テキスト、または content パートの配列です。ゲートウェイはパート配列を変更せずに転送します。画像パート（image_url）は画像入力に対応するモデルでのみ動作します。モデルページを確認してください。
assistant メッセージ
- rolestring必須対応
  "assistant" を指定します。
  指定できる値
  assistant
- contentstring | null対応
  以前のモデルの応答です。応答がツール呼び出しだった場合は null にできます。
- tool_callsarray対応
  モデルが返した tool_calls 配列です。対応する tool メッセージの前に、変更せずに送り返します。
tool メッセージ
- rolestring必須対応
  "tool" を指定します。
  指定できる値
  tool
- tool_call_idstring必須対応
  この結果が対応するツール呼び出しの id です。
- contentstring必須対応
  ツールの実行結果です。通常は JSON 文字列です。
max_tokensinteger対応
送信した値のままモデルサーバーに渡されます。この上限で生成が止まると（finish_reason: "length"）、非ストリーミングのレスポンスで content が空になることがあります。
完全な定義を見る
streamboolean対応
ゲートウェイは文字列 "true" と数値 1 も true として読み取り、転送前にこのフィールドを boolean に書き換えます。
デフォルト
false
完全な定義を見る
toolsarray対応
OpenAI の function 定義の形式で送信します。
完全な定義を見る
function ツール
- typestring必須対応
  "function" を指定します。
  指定できる値
  function
- function.namestring必須対応
  モデルが tool_calls で使用する名前です。
- function.descriptionstring必須対応
  関数の動作の説明です。description のない関数は 400 で拒否されます。
- function.parametersobject対応
  関数の引数の 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_optionsobject対応
ストリーミングレスポンスのオプションです。stream: true と一緒に送る場合にのみ使用してください。
usage オプション
- include_usageboolean対応
  true の場合、ストリームの最後に、choices が空で usage オブジェクトにトークン数と cost を含むチャンクが 1 つ追加されます。ゲートウェイはトークン計測のためにすべてのストリーミングリクエストでこの値を設定し、指定がなかった場合は usage チャンクを取り除きます。
  デフォルト
  false
parallel_tool_callsboolean非対応
モデルページで並列ツール呼び出しが対応となっているモデルでのみ適用され、qwen3-32b は該当しません。gpt-oss-120b での実測では、リクエストは 200 で受け付けられ、モデルは応答ごとに最大 1 つのツールだけを呼び出しました。qwen3-32b では parallel_tool_calls の設定が適用されません。これは応答のツール呼び出しが 1 つだけという意味ではありません。parallel_tool_calls: false を送っても、1 つの応答に複数のツール呼び出しが含まれることがあります。tool_calls のすべての項目に、それぞれ tool メッセージで応答してください。
reasoning_effortstring対応
送信した値のままモデルに渡されます。gpt-oss-120b は low、medium、high を受け付けます。他のモデルがこの値に従うかは公開されていません。値が高いほど reasoning トークンを多く使うため、レイテンシと出力トークンが増えます。
指定できる値
low, medium, high
temperaturenumber転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
範囲
0–2
top_pnumber転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
範囲
0–1
ninteger転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
seedinteger転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
presence_penaltynumber転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
範囲
-2–2
frequency_penaltynumber転送のみ
モデルサーバーに転送されます。Kiln は動作を検証していません。
範囲
-2–2
stopstring | array無視
受け付けられますが、適用されません。stop 文字列の後も生成が続きます。
response_formatobject非対応
json_object と json_schema はまだ動作しません。リクエストは 200 で受け付けられますが、content が空で返されます。JSON が必要な場合は、プロンプトで JSON のみで回答するよう指示し、クライアント側で結果をパースして検証してください。
ignore_eosboolean非対応
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 を含むレスポンスヘッダーです。ログと一緒に保存してください。

ストリームチャンク

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

フィールド	型	説明
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 チャンクに追加します。

エラー

メッセージの文言ではなく、HTTP ステータスと error.code で分岐してください。error.code の欄が空の場合、ボディに code はありません。すべてのステータスコードはエラーページにあります。

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

401、402、403、429 は、リクエストがこのエンドポイントに届く前にゲートウェイが返します。これらは API リファレンスページに一度だけ記載しています。

制限

コンテキスト長、リクエストボディのサイズ、タイムアウト、組織ごとのレート制限もここに適用され、 API リファレンスページに一度だけ記載しています。

429 のヘッダーと再試行の方法はレート制限ページにあります。