> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wangenhui.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Response API 入門：次世代のモデル API を理解する

> OpenAI Response API の主要概念、Chat Completions との違い、ユースケース、ベストプラクティスを解説します。

Response API は、OpenAI が提供する次世代のモデル API です。ステートフルなマルチターン会話、複数ツールの協調、推論モデルの出力、マルチモーダル入力を、より簡潔で強力なプログラミングモデルに統合しています。

## Response API とは

Response API（`/v1/responses`）は 2025 年に OpenAI が公開した統一 API です。従来 Chat Completions、Assistants、Tools などに分散していた機能を 1 つのエンドポイントに集約し、以下を 1 回の呼び出しで実現できます。

* マルチターン会話とコンテキスト管理
* ビルトインツール（Web 検索、ファイル検索、コードインタープリタ、コンピュータ操作など）
* カスタム関数呼び出し
* 推論モデル（o シリーズなど）の思考過程の出力
* テキスト、画像、音声などのマルチモーダル入出力

## Chat Completions との主な違い

<CardGroup cols={2}>
  <Card title="ステートフル vs ステートレス" icon="database">
    Chat Completions は毎回全履歴を送信する必要があります。Response API は `previous_response_id` で直前のレスポンスを継続でき、コンテキストをサーバー側で管理します。
  </Card>

  <Card title="統一された入力構造" icon="layers">
    Chat Completions は `messages` 配列を使います。Response API は `input` フィールドで、文字列、メッセージ配列、画像やファイルを含むマルチモーダル構造を受け付けます。
  </Card>

  <Card title="ビルトインツール" icon="puzzle">
    `web_search`、`file_search`、`code_interpreter`、`computer_use` などのホスト型ツールを標準サポートし、自前実装が不要です。
  </Card>

  <Card title="推論の可視化" icon="lightbulb">
    o1 や o3 などの推論モデルでは、`reasoning` アイテムが出力に含まれ、思考過程の追跡やデバッグが容易です。
  </Card>
</CardGroup>

## もっともシンプルな呼び出し

```bash cURL theme={null}
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "量子もつれを一文で説明してください。"
  }'
```

レスポンスの主なフィールド：

* `id`：このレスポンスの一意な ID。次回の継続に使用可能
* `output`：モデルが生成したアイテム配列（テキスト、ツール呼び出し、推論など）
* `output_text`：全テキストを連結した便利フィールド
* `usage`：トークン消費量

## マルチターン会話：手動での履歴連結を卒業

従来は毎ターン全 `messages` を送っていました。Response API は前回の `id` を渡すだけです。

```python Python theme={null}
from openai import OpenAI

client = OpenAI()

first = client.responses.create(
    model="gpt-4.1",
    input="SF 小説を 3 冊おすすめしてください。"
)

second = client.responses.create(
    model="gpt-4.1",
    previous_response_id=first.id,
    input="その中で最も短い作品はどれくらいの分量ですか？"
)

print(second.output_text)
```

サーバー側で前回のコンテキストを自動的に取り込むため、クライアント実装がシンプルになり、重複トークンの課金も削減できます。

## ビルトインツール：一行で Web 検索を有効化

```python Python theme={null}
response = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "web_search"}],
    input="2026 年のノーベル物理学賞受賞者は誰ですか？"
)

print(response.output_text)
```

検索サービス、スクレイピング、引用の組み立てを自作する必要はなく、モデルが検索の要否と統合方法を判断します。同様に `file_search`（アップロードファイルの RAG）、`code_interpreter`（サンドボックス実行）、`computer_use`（ブラウザ／デスクトップ操作）が利用可能です。

## ストリーミング出力

Response API は Server-Sent Events で構造化イベントを返すため、Chat Completions の delta より扱いやすくなっています。

```python Python theme={null}
stream = client.responses.create(
    model="gpt-4.1",
    input="秋についての短い詩を書いてください。",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
```

代表的なイベントには `response.created`、`response.output_text.delta`、`response.tool_call.created`、`response.completed` などがあります。

## Response API を使うべきタイミング

<Tip>
  **Response API が向いているケース**

  * エージェントや多段タスクを構築する
  * Web 検索、ファイル検索、コード実行などのホスト型ツールが必要
  * o1、o3 などの推論モデルで思考過程を確認したい
  * マルチターン会話のステート管理を簡素化したい
</Tip>

<Note>
  **当面 Chat Completions で十分なケース**

  * `messages` ベースの既存コードが多く、短期的な移行メリットが小さい
  * ステートレスな単発補完だけで、ツールも不要
  * まだ Response API に対応していないサードパーティラッパーに依存している
</Note>

## 移行のヒント

<Steps>
  <Step title="エンドポイントを置き換える">
    `/v1/chat/completions` を `/v1/responses` に変更し、`messages` を `input` に置き換えます。
  </Step>

  <Step title="previous_response_id でセッション管理">
    クライアントで全履歴を保存するのをやめ、直前の `response.id` のみを保持します。
  </Step>

  <Step title="ビルトインツールに置き換える">
    自作の検索、RAG、コード実行を `web_search`、`file_search`、`code_interpreter` に置き換えられるか評価します。
  </Step>

  <Step title="新しいイベントストリームへ対応">
    ストリーミングを使っている場合、delta 解析を `event.type` ベースのディスパッチに変更します。
  </Step>
</Steps>

## まとめ

Response API は「モデル + ツール + ステート + マルチモーダル」を 1 つのインターフェイスに集約した、エージェント時代の推奨エントリーポイントです。新規プロジェクトは Response API から始めるのがおすすめで、既存プロジェクトも機能単位で段階的に移行し、ビルトインツールとステート管理による複雑さの削減を優先的に享受するとよいでしょう。