# Responses

Source: https://aiand-docs-staging.pages.dev/ja/api/responses/

```http
POST /v1/responses
```

指定した入力に対してモデル応答を生成します。[OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create) と互換です。

## リクエストボディ

| パラメータ | 型 | 必須 | 説明 |
|-----------|------|----------|-------------|
| `model` | string | はい | モデル ID |
| `input` | string \| array | はい | テキスト文字列 (ユーザーメッセージとして扱われる) または入力アイテムの配列 |
| `instructions` | string | いいえ | コンテキストの先頭に追加されるシステム / デベロッパーメッセージ |
| `stream` | boolean | いいえ | SSE でストリーミング。デフォルト: `false` |
| `temperature` | number | いいえ | サンプリング温度 (0〜2) |
| `top_p` | number | いいえ | Nucleus サンプリング (0より大きく1以下) |
| `max_output_tokens` | integer | いいえ | 生成トークン数の上限 |
| `tools` | array | いいえ | モデルが呼び出し可能な関数ツール |
| `tool_choice` | string \| object | いいえ | `"none"`、`"auto"`、`"required"`、または特定のツール |
| `parallel_tool_calls` | boolean | いいえ | 並列ツール呼び出しを許可 |
| `reasoning` | object | いいえ | `{ "effort": …, "summary": "auto"\|"concise"\|"detailed" }`。`effort` はモデルごとにその [`reasoning_efforts`](/ja/models/catalog/) と照合されます。一覧にないレベルは一つ上のレベル(なければ最も高いレベル)で実行され、送信したレベルより高コストになる場合があります。適用されたレベルは `X-Reasoning-Effort` で返されます。effort の語彙にない値は 400 になります。 |
| `truncation` | string | いいえ | `"auto"` (コンテキストに収まるよう切り詰め) または `"disabled"` |
| `metadata` | object | いいえ | トラッキング用のキーバリューペア |
| `text` | object | いいえ | テキストレスポンスフォーマットの設定 |
| `seed` | integer | いいえ | 決定論的サンプリングのシード |
| `stop` | string \| string[] | いいえ | 最大 4 つの停止シーケンス |
| `top_k` | integer | いいえ | Top-k サンプリング (プロバイダ依存) |
| `repetition_penalty` | number | いいえ | 繰り返しペナルティ (プロバイダ依存) |

モデルが reasoning をオフにできるのは、その levels に `none` が含まれる場合だけです。`none` を公開していないモデルへ `reasoning.effort` に `none` を送ると 400 になります。エラー文は [エラー](/ja/errors/#reasoning-をオフにする) にあります。

### 入力タイプ

**単純な文字列:**

```json
{
  "model": "google/gemma-4-31b-it",
  "input": "Explain quantum computing in one paragraph."
}
```

**構造化された入力アイテム:**

```json
{
  "model": "google/gemma-4-31b-it",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this image" },
        { "type": "input_image", "image_url": "https://..." }
      ]
    }
  ]
}
```

**入力アイテムのタイプ:**

| タイプ | 説明 |
|------|-------------|
| メッセージ | `{ "role": "user"\|"assistant"\|"developer"\|"system", "content": string \| content[] }` |
| 関数呼び出し | `{ "type": "function_call", "call_id": "...", "name": "...", "arguments": "..." }` |
| 関数呼び出しの出力 | `{ "type": "function_call_output", "call_id": "...", "output": "..." }` |

**コンテンツタイプ:** `input_text`、`input_image`、`input_file`

`input_image` の `image_url`、`input_file` の `file_url`、MCP ツールの `server_url` は [URL の要件](/ja/capabilities/vision/#url-の要件) を満たす必要があります。

PDF は、`input_file` にドキュメントの `file_id` を指定するか、`file_data` (`data:application/pdf;base64,...`) としてインラインで送信します。インラインの PDF は `document` ファイルとして保存され、制限は [Chat Completions](/ja/api/chat-completions/) と同じです（[ゼロデータリテンション](/ja/organizations/zero-data-retention/)の組織では保存されずメモリ上で描画され、[専用の制限](/ja/organizations/zero-data-retention/#インライン-pdf)が適用されます）。サーバーが各ページを画像に変換し、1 ページにつき 1 つの `input_image` パートとしてモデルに渡します。

## レスポンス

```json
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "created_at": 1700000000,
  "model": "google/gemma-4-31b-it",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses quantum bits (qubits)..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 80,
    "total_tokens": 95
  }
}
```

### レスポンスのステータス

| ステータス | 説明 |
|--------|-------------|
| `completed` | 生成完了 |
| `failed` | 生成失敗 (`error` フィールドを参照) |
| `in_progress` | 生成中 (ストリーミング) |
| `incomplete` | 途中で停止 (`incomplete_details.reason` を参照) |
| `cancelled` | リクエストがキャンセルされた |
| `queued` | 処理待ち |

### 使用量 (usage)

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `input_tokens` | integer | 入力で消費したトークン数 |
| `output_tokens` | integer | 生成された出力トークン数 |
| `total_tokens` | integer | 入力と出力の合計 |
| `input_tokens_details` | object | `{ cached_tokens }` |
| `output_tokens_details` | object | `{ reasoning_tokens }` |

## マルチターン会話

レスポンスオブジェクトは保存されないため、毎回のリクエストでそれまでのターンを `input` に含めて送信してください。モデルが行った `function_call` も、対応する `function_call_output` と合わせて含めます。空でない `previous_response_id` または `item_reference` 入力アイテム（`{ "id": "..." }` だけで送ったものも含む）を含むリクエストは `400 unsupported_value` で拒否されます。`store` 自体は受け付けますが、無視されます。ただし、Vercel AI SDK など `store: true` がデフォルトのクライアントはそれまでのターンを `item_reference` として送るため、`store: false` を指定してください。ただし、インライン PDF や記録されたリクエスト本文など、リクエストに含まれる内容が保存される場合はあります。何がどれだけの期間保存されるかは[ゼロデータリテンション](/ja/organizations/zero-data-retention/)に記載しています。

```json
{
  "model": "google/gemma-4-31b-it",
  "input": [
    { "role": "user", "content": "Explain quantum computing in one paragraph." },
    { "role": "assistant", "content": "Quantum computing uses quantum bits (qubits)..." },
    { "role": "user", "content": "Now explain it to a 5-year-old." }
  ]
}
```