本文へスキップ
Kiln
Markdown で表示

API リファレンス

このページには、エンドポイントに共通する内容をまとめています。Base URL、認証、複数のエンドポイントが受け取るパラメータ、レスポンスの形式、ストリーミング、ゲートウェイが返すエラーと適用する制限です。以下の各エンドポイントページには、そのエンドポイント固有の内容だけを置き、残りはこのページを参照します。

Base URL

URL
https://api.bricksum.com/v1

以下のすべてのパスは、この Base URL からの相対パスです。Anthropic の SDK は /v1 を自分で付けるため、https://api.bricksum.com を指定してください。

認証

API キーを Authorization ヘッダーに Bearer トークンとして送信してください。x-api-key ヘッダーは Authorization がない場合にのみ読み取ります。両方がある場合は Authorization を使用し、Authorization の値が Bearer トークンの形式でなければ、x-api-key にフォールバックせずに拒否します。使用できるキーがないリクエストは、エンドポイントに届く前に 401 で拒否されます。

ゲートウェイは anthropic-version と anthropic-beta ヘッダーを読み取らないため、これらのヘッダーの有無にかかわらずリクエストを同じように処理し、?beta=true のようなクエリ文字列も受け付けます。上のルールの例外は GET /key だけです。このルートは Kiln API が処理し、キーを Bearer トークンとしてのみ受け取ります。詳細はそのページに記載しています。 認証

エンドポイント

現在提供しているエンドポイントです。クライアントがすでに使っている形式に合わせて選んでください。ゲートウェイはいずれも同じ方法で計測します。

エンドポイント形式ストリーミング用途
POST/chat/completionsOpenAIdata: チャンク会話とツール呼び出しに使います。ほとんどの OpenAI クライアントが使うエンドポイントです。
POST/completionsOpenAIdata: チャンクプロンプトに続くテキストを生成します。会話とツール呼び出しには対応しません。
POST/responsesOpenAI型付きイベントResponses 形式です。Codex CLI が使用します。状態を保存しないため、毎回会話全体を input に入れて送信します。
POST/messagesAnthropic型付きイベントAnthropic Messages 形式です。Claude Code が使用します。chat completions に変換し、同じ方法で計測します。
POST/messages/count_tokensAnthropicなしMessages リクエストの入力トークン数を数えます。推論は実行されず、課金されません。
GET/modelsOpenAIなしゲートウェイが現在提供できるモデル ID の一覧です。課金されません。
GET/keyKilnなし呼び出しに使ったキーのプロジェクト、ステータス、支出上限、有効期限、支出額です。ゲートウェイではなく Kiln API が処理します。

共通のリクエストパラメータ

複数のエンドポイントが受け取るリクエストパラメータです。ここに一度だけ記載し、各エンドポイントページには名前と、そのエンドポイントで異なる点だけを記載しています。

対応状況

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

    モデル ID です（例：qwen3-32b）。送信できる ID は GET /models で取得します。カタログにない ID は、モデルに届く前に拒否されます。OpenAI 形式のエンドポイントは 404（model_not_found）、Anthropic 形式のエンドポイントは 404（not_found_error）を返します。

  • messagesarray必須対応

    これまでの会話です。古いメッセージから順に並べます。配列が空または未指定の場合は 400 で拒否され、課金されません。メッセージは role と content を持ち、content が取れる形は OpenAI 形式と Anthropic 形式のエンドポイントで異なるため、各エンドポイントページに記載しています。

  • max_tokensinteger対応

    生成する最大トークン数です。reasoning トークンも含まれるため、余裕を持って設定してください。上限に達したときの動作と、このフィールドがないときの動作はエンドポイントごとに異なります。

  • streamboolean対応

    true の場合、レスポンスは 1 つの JSON ボディではなく server-sent events のストリームになります。JSON の boolean で送信してください。OpenAI 形式のエンドポイントは data: 行を送り、data: [DONE] でストリームを終えます。Anthropic 形式の Messages エンドポイントは型付きのイベントを送ります。

    デフォルト
    false
  • toolsarray対応

    モデルが呼び出せる関数の定義です。それぞれに名前、description、引数の JSON Schema が必要で、フィールド名は 2 つの形式で異なります。どのモデルがどのツール選択の方式を適用するかは、モデルページの対応機能表に記載しています。

  • tool_choicestring | object対応

    モデルがツールを呼び出す必要があるかどうかを指定します。自動のツール選択ではモデルが判断します。強制的なツール選択はすべてのモデルで適用されるわけではなく、どのモデルがどの方式を適用するかはモデルページの対応機能表に記載しています。qwen3-32b では、強制的なツール選択が明確なエラーなしに失敗します（2026-09-26 実測）。tool_choice を "required" にすると本文が平文 "Internal Server Error" の HTTP 500 が返り、関数を指定すると arguments が空の 200（finish_reason "stop"）が返ります。どちらも 4xx ではないため、再試行では解決しません。tool_choice は "auto" のみを送ってください。

どのエンドポイントがこれらのパラメータを受け取るか、そのエンドポイントで必須かどうかは、各エンドポイントページに記載しています。エンドポイントページに記載のないパラメータは、送信した値のままモデルサーバーに転送されます。Kiln は動作を検証していません。

レスポンスの形式

リクエストが成功すると、そのエンドポイントの形式の JSON ボディとともに 200 を返します。計測対象のエンドポイントで共通する項目は 2 つです。

フィールド型説明
usageobjectこのリクエストのトークン数です。フィールド名はエンドポイントの形式に従い、各エンドポイントページに記載しています。クレジットから差し引かれる金額（USD）である usage.cost は、OpenAI 形式の JSON レスポンスと、Chat completions・Completions のストリームの最後のチャンクにゲートウェイが追加します。Responses のストリームイベントと Messages のレスポンスにはトークン数だけが入り、cost フィールドはありません。
X-Neocloud-Generation-Idheaderこのリクエストの usage イベント ID を含むレスポンスヘッダーです。ログと一緒に保存してください。推論を実行しない GET /models と POST /messages/count_tokens は usage イベントを発行しないため、このヘッダーも送りません。

ストリーミング

stream: true の場合、レスポンスは server-sent events のストリームになります。OpenAI 形式のエンドポイントはチャンクごとに data: 行を 1 つ送り、data: [DONE] で終えます。Responses と Messages は、event: 行と続く data: 行からなる型付きのイベントを送ります。どちらの場合も生成が終わるまで接続が開いたままなので、長いリクエストが下記のタイムアウトに達しません。チャンクのフィールドとイベントの型は、各エンドポイントページに記載しています。 ストリーミング

ゲートウェイが返すエラー

以下のエラーは、リクエストがエンドポイントに届く前にゲートウェイが返すため、ゲートウェイが処理するすべてのエンドポイントで同じ形で現れます。メッセージの文言ではなく、HTTP ステータスで分岐してください。不正なリクエストボディ、存在しないモデル ID、誤ったメソッドのようにエンドポイント自身が返すエラーは各エンドポイントページにあり、すべてのステータスコードはエラーページにあります。 エラー

ステータス原因対処
401API キーがない、形式が不正、未登録、または期限切れです。x-api-key または Authorization ヘッダーとキーの有効期限を確認してください。
402クレジットが尽きた、組織が月間予算に達した、またはキーが支出上限に達しました。チャージするか、管理者に予算または上限の引き上げを依頼してください。
403API キーが停止または失効しています。コンソールでキーを再有効化するか、新しいキーを作成してください。
429組織の 1 分あたりのリクエスト数またはトークン数の上限を超えました。x-ratelimit-reset 秒待ってから再試行してください。

制限

  • コンテキスト長：モデルごとに異なり、プロンプトと出力の合計です。モデル別の値はモデルページに記載されています。これを超えるリクエストは 400 で拒否されます。
  • リクエストボディ：ゲートウェイは先頭から最大 8 MiB までしか読み取りません。ボディはそれより小さくしてください。
  • タイムアウト：ゲートウェイはリクエストを 60 分後に終了します。非ストリーミングのリクエストは完了するまでバイトを送信せず、ネットワークエッジがそのような接続を約 100 秒後に切断することがあります。長い生成は stream: true で送信してください。
  • 組織ごとのレート制限：既定で 1 分あたり 60 リクエスト、設定されている場合は 1 分あたりのトークン数の上限、同時リクエスト 8 件です。

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

現在のサービングスタックは、OpenAI のパラメータすべてを適用するわけではありません。各エンドポイントページにパラメータごとの対応状況を示しており、既知の制限は OpenAI からの移行 ページの 1 か所にまとめています。

POST/chat/completionsPOST/completionsPOST/responsesPOST/messagesPOST/messages/count_tokensGET/modelsGET/key