# Responses

> POST /responses のリファレンスです。パラメータごとの対応状況、ストリームイベント、usage.cost が含まれる位置、エラー、サンプルを説明します。レスポンスは保存されず、previous_response_id は拒否されます。

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

`POST https://api.bricksum.com/v1/responses`

OpenAI Responses 形式でモデルの応答を生成します。ゲートウェイはリクエストボディとストリームイベントを変更せずにモデルサーバーとやり取りし、トークンを計測します。ゲートウェイはレスポンスを保存しないため、リクエストごとに会話全体を input に入れて送信してください。

Codex CLI はこのエンドポイントで Kiln と通信します。プロバイダーブロックは [連携ページの Codex CLI の項目](https://kiln.bricksum.com/docs/ja/integrations#codex)にあります。

## 認証

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

## リクエストボディ

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

### 共通パラメータ

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

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `model` | string | 必須 |  | 対応 | 共通の定義と同じです。 |
| `stream` | boolean |  | `false` | 対応 | ゲートウェイは文字列 "true" と数値 1 も true として読み取り、転送前にこのフィールドを boolean に書き換えます。Responses のリクエストに stream_options は追加しません。 |
| `tools` | array |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `tool_choice` | string \| object |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 qwen3-32b では、強制的なツール選択が明確なエラーなしに失敗します（2026-09-26 実測）。tool_choice を "required" にすると本文が平文 "Internal Server Error" の HTTP 500 が返り、関数を指定すると arguments が空の 200（finish_reason "stop"）が返ります。どちらも 4xx ではないため、再試行では解決しません。tool_choice は "auto" のみを送ってください。 |

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

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `input` | string \| array | 必須 |  | 対応 | テキストのプロンプト、または入力項目の配列（メッセージ、関数呼び出し、関数呼び出しの結果）です。毎回、会話全体を送信してください。ゲートウェイは値を変更せずに転送し、検証は行いません。 |
| `previous_response_id` | string |  |  | 非対応 | モデルに届く前に 400（unsupported_parameter）で拒否され、課金されません。ゲートウェイはレスポンスを保存しないため、引き継ぐ以前のレスポンスがありません。null は受け付けられます。 |
| `store` | boolean |  |  | 転送のみ | 送信した値のままモデルサーバーに転送されます。値にかかわらず、Kiln 経由でレスポンスを再取得することはできません。GET /responses/{id}、DELETE /responses/{id}、GET /responses/{id}/input_items は 404（not_found）を返します。 |
| `instructions` | string |  |  | 転送のみ | このリクエストに適用するシステムレベルの指示です。モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `max_output_tokens` | integer |  |  | 転送のみ | 生成する最大トークン数です。モデルサーバーに転送されます。Kiln は動作を検証していません。モデルサーバーが生成を途中で終えた場合は response.incomplete で終了し、使用したトークンは課金されます。 |
| `parallel_tool_calls` | boolean |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 qwen3-32b では parallel_tool_calls の設定が適用されません。これは応答のツール呼び出しが 1 つだけという意味ではありません。parallel_tool_calls: false を送っても、1 つの応答に複数のツール呼び出しが含まれることがあります。tool_calls のすべての項目に、それぞれ tool メッセージで応答してください。 |
| `reasoning` | object |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `text` | object |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `temperature` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: 0–2 |
| `top_p` | number |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 範囲: 0–1 |
| `truncation` | string |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `include` | array |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `metadata` | object |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| `user` | string |  |  | 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |

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

## レスポンスボディ

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `id` | string | response の ID です。この ID で後からレスポンスを取得することはできません。 |
| `object` | string | "response" です。 |
| `status` | string | "completed" です。生成が途中で終わった場合は "incomplete" です。 |
| `output` | array | モデルサーバーが返した出力項目です。output_text パートを持つメッセージと関数呼び出しが入ります。変更せずに転送されます。 |
| `usage.input_tokens` | integer | 入力トークン数です。 |
| `usage.output_tokens` | integer | 出力トークン数です。 |
| `usage.total_tokens` | integer | 入力と出力のトークン数の合計です。 |
| `usage.input_tokens_details.cached_tokens` | integer | プレフィックスキャッシュから処理された入力トークン数です。モデルサーバーが報告した場合にのみ含まれます。 |
| `usage.cost` | number | このリクエストでクレジットから差し引かれる金額（USD）です。ゲートウェイは非ストリーミングのレスポンスにのみ追加します。 |
| `X-Neocloud-Generation-Id` | header | このリクエストの usage イベント ID を含むレスポンスヘッダーです。ストリーミングのレスポンスにも付きます。ログと一緒に保存してください。 |

## ストリームイベント

stream: true の場合、モデルサーバーは型付きのイベントを送信します。event: 行に型が入り、続く data: 行の JSON にも同じ値が type として入ります。ゲートウェイはすべてのイベントを変更せずに転送し、最後のイベントからトークン数を読み取ります。ストリーミングのイベントでは usage が response の中にあるため、ゲートウェイは usage.cost を追加しません。ストリーミングリクエストのコストは、response.usage とモデルの単価から計算するか、コンソール → 使用量で確認してください。

| イベント | 説明 |
| --- | --- |
| `response.created` | モデルサーバーから変更せずに転送されます。 |
| `response.output_text.delta` | モデルサーバーから変更せずに転送されます。delta に新しく生成されたテキストが入ります。 |
| `response.completed` | 正常に終了した生成の最後のイベントです。response.usage に課金対象のトークン数が入ります。 |
| `response.incomplete` | max_output_tokens などで途中で終わった生成の最後のイベントです。response.usage にトークン数が入り、課金されます。 |
| `response.failed` | 生成が失敗しました。イベントに usage が含まれていても、リクエストは課金されません。 |
| `error` | モデルサーバーからのエラーイベントです。リクエストは課金されません。 |

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `type` | string | イベントの型です。上記のいずれかの値です。モデルサーバーが他の response.* イベントを送信することがあり、変更せずに転送されます。 |
| `delta` | string | response.output_text.delta で、新しく生成されたテキストです。 |
| `response` | object | response.created と最後のイベントに入る response オブジェクトです。usage は最後のイベントまで null です。 |
| `response.usage` | object | response.completed と response.incomplete に入ります。input_tokens、output_tokens、total_tokens を含みます。ゲートウェイはこのオブジェクトを取り除かず、cost フィールドも追加しません。 |

keepalive コメントと切断時の動作は [ストリーミング](https://kiln.bricksum.com/docs/ja/streaming) ページで説明しています。

## エラー

| ステータス | error.code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | `unsupported_parameter` | リクエストに previous_response_id が含まれています。 | このフィールドを削除し、会話全体を input に入れて送信してください。 |
| 400 |  | モデルサーバーがリクエストを拒否しました。不正な JSON、無効なパラメータ、モデルページに記載のモデル別コンテキスト長を超えるコンテキストが原因です。 | リクエスト内容を修正してください。そのまま再試行しないでください。 |
| 404 | `model_not_found` | モデル ID がカタログにありません。 | GET /models で ID を確認してください。 |
| 404 | `not_found` | GET /responses/{id}、DELETE /responses/{id}、GET /responses/{id}/input_items のいずれかを呼び出しました。ゲートウェイはレスポンスを保存しません。 | 会話はクライアント側で保持し、input に入れて送信してください。 |
| 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/responses \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "instructions": "Answer briefly.",
    "input": "Hello!"
  }'
```

**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.responses.create(
    model="qwen3-32b",
    instructions="Answer briefly.",
    input="Hello!",
)
print(resp.output_text)
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.responses.create({
  model: "qwen3-32b",
  instructions: "Answer briefly.",
  input: "Hello!",
});
console.log(resp.output_text);
console.log(resp.usage);
```

### レスポンス

**200 OK**
```json
{
  "id": "resp_...",
  "object": "response",
  "created_at": 1710000000,
  "model": "qwen3-32b",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello! How can I help?" }]
    }
  ],
  "usage": {
    "input_tokens": 9,
    "output_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}
```

**text/event-stream**
```text
event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress","usage":null}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed","usage":{"input_tokens":9,"output_tokens":12,"total_tokens":21}}}
```

**400 Bad Request**
```json
{
  "error": {
    "message": "'previous_response_id' is not supported: responses are not stored on this gateway. Send the full conversation in 'input'.",
    "type": "invalid_request_error",
    "param": "previous_response_id",
    "code": "unsupported_parameter"
  }
}
```