DEV Community

Cover image for OpenAI Responses API 使い方
Akira
Akira

Posted on • Originally published at apidog.com

OpenAI Responses API 使い方

このガイドでは、OpenAI Responses API を実装・検証する手順をエンドツーエンドで説明します。POST /v1/responses にリクエストを送信し、ネストされた output を読み取り、組み込みツールを有効化し、previous_response_id で会話状態を継続し、最後に Apidog で契約テストまで行います。Responses API は、モデル出力を生成するための OpenAI の新しいインターフェースであり、公式のResponsesガイドでは、新しいプロジェクトに推奨される理由が説明されています。以前のエンドポイントをテストしていた場合でも、ChatGPT API テストガイドの考え方を多く再利用できます。

今すぐ Apidog を試す

まず必要なもの

実装前に、以下を準備します。

  • OpenAI API キー コマンドや共有ファイルに直接貼り付けず、環境変数で管理します。
  • 利用可能なモデル名 OpenAI ダッシュボードで、あなたのアカウントが呼び出せるモデルを確認します。
  • HTTP リクエストを送信して JSON を確認する手段 最初は curl で十分です。継続的な検証やモックには Apidog を使います。

Responses API の中心は、次の単一エンドポイントです。

POST /v1/responses
Enter fullscreen mode Exit fullscreen mode

API リファレンスはこちらです。

POST /v1/responses

このエンドポイントに model と input を送ると、テキスト、関数呼び出し、Web 検索やファイル検索などの OpenAI ホスト型ツールの結果を含むレスポンスオブジェクトが返ります。

Responses API の重要な特徴は次の2つです。

  1. 組み込みツールをサーバーサイドで実行できる

    Web 検索、ファイル検索、コード実行などを自前で実装せずに利用できます。

  2. 会話状態を保持できる

    各レスポンスには id が付与されます。次のリクエストで previous_response_id にその id を渡すと、会話履歴を再送信せずにスレッドを継続できます。

Chat Completions との違いを知る

POST /v1/chat/completions を使ったことがある場合、主な違いはリクエスト・レスポンスの形状と状態管理です。

Chat Completions は messages 配列を受け取り、choices を返します。会話履歴はアプリ側で管理し、毎回すべての履歴を再送信します。

Responses API は input を受け取り、output を返します。必要に応じてサーバーサイドに状態を保存し、ホスト型ツールも同じレスポンス内で扱えます。

側面 Chat Completions Responses API
エンドポイント POST /v1/chat/completions POST /v1/responses
リクエストボディ messages 配列 input + instructions
出力形式 choices[].message output
会話の状態 全履歴を再送信 store + previous_response_id
組み込みツール 自分で実装 web_search, file_search, code_interpreter など
ステータス サポート中、非推奨の発表なし 新しいプロジェクトに推奨

Chat Completions がすぐに廃止されるわけではありません。OpenAI は引き続きサポートすると述べています。一方、Assistants API は 2025年8月26日に非推奨化が発表され、2026年8月26日に廃止予定のため、新しいエージェント実装は Responses API から始めるのが安全です。

最初のリクエストを送る

まず、API キーを環境変数に設定します。

export OPENAI_API_KEY="your_api_key"
Enter fullscreen mode Exit fullscreen mode

次に、最小構成で POST /v1/responses を呼び出します。model は、あなたのアカウントで利用可能なモデル名に置き換えてください。

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'
Enter fullscreen mode Exit fullscreen mode

このリクエストで指定している主なフィールドは次のとおりです。

  • model 使用するモデル名。
  • input ユーザー入力またはプロンプト。
  • instructions システムレベルの指示。
  • store true の場合、レスポンスを保存し、後続リクエストで会話を継続できます。

応答を読む

省略されたレスポンス例です。

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}
Enter fullscreen mode Exit fullscreen mode

実装時に特に重要なのは、テキストがトップレベルには存在しない点です。

生の HTTP JSON では、主な出力テキストは次のパスにあります。

output[0].content[0].text
Enter fullscreen mode Exit fullscreen mode

SDK では output_text のような便利なアクセサーが提供される場合がありますが、これは SDK 側のヘルパーです。HTTP レスポンスを直接扱う場合は、ネストされた output を読む必要があります。

実装で見るべき代表的なフィールドは次のとおりです。

id
status
output[0].content[0].text
usage.total_tokens
Enter fullscreen mode Exit fullscreen mode

id は会話継続に使います。usage.total_tokens は、その呼び出しで使用されたトークン量の確認に使います。

組み込みツールを追加する

Responses API では、tools 配列にツールを指定すると、モデルが必要に応じてツールを呼び出します。

代表的な組み込みツールは次のとおりです。

  • web_search 引用付きのリアルタイムインターネット検索。
  • file_search アップロード済みファイルに対する検索。
  • code_interpreter サンドボックス内でのコード実行と分析。
  • computer_use コンピュータインターフェースの操作。
  • image_generation インラインでの画像生成。

Web 検索を有効にする例です。

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

ツールが呼び出されると、output 配列には最終的な message だけでなく、ツール呼び出しを表すアイテムも含まれます。たとえば Web 検索では、web_search_call のようなアイテムが確認できます。

テストでは、単にテキストが返ることだけでなく、ツール呼び出しが実際に発生したことも検証できます。

呼び出しをまたいで会話を継続する

Responses API の状態管理は、主に次の2つで行います。

  • store
  • previous_response_id

store はデフォルトで true です。OpenAI はレスポンスオブジェクトを保存し、id を返します。保存されたレスポンスはデフォルトで30日間保持されます。

次のリクエストで、その id を previous_response_id として渡すと、会話履歴を再送信せずにスレッドを継続できます。

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

ステートレスにしたい場合、またはデータ保持ゼロの要件がある場合は、store を false に設定し、コンテキストを自分で管理します。

{
  "model": "gpt-5.5",
  "input": "Summarize this text in one sentence.",
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

リアルタイムの音声・オーディオフローでは、OpenAI は別のインターフェースを使います。そのケースは GPT リアルタイム API ガイドで扱っています。

複数ステップのエージェントを構成する場合は、OpenAI Agents SDK のパターンとも近い考え方になります。

Apidog でテストする方法

Apidog は API のテスト、設計、モックのためのプラットフォームです。OpenAI SDK やコードライブラリではないため、Python や JavaScript のクライアントコードを書く必要はありません。

代わりに、/v1/responses への生の HTTP リクエストを作成し、送信し、返ってきた JSON に対してアサーションを設定します。

1. API キーを環境変数に保存する

Apidog で環境を作成します。たとえば、次のような環境名にします。

OpenAI Prod
Enter fullscreen mode Exit fullscreen mode

そこに、次の変数を追加します。

OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

値はリクエスト本文や共有コレクションに直接書かず、環境変数として保存します。

2. POST /v1/responses リクエストを作成する

Apidog で新しいリクエストを作成します。

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

ヘッダーを追加します。

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

ボディは JSON に設定し、次のような内容を入力します。

{
  "model": "gpt-5.5",
  "input": "Write one sentence describing what an API mock server does.",
  "instructions": "You are a concise technical writer. No marketing language.",
  "store": true
}
Enter fullscreen mode Exit fullscreen mode

送信すると、Apidog 上で整形されたレスポンス JSON を確認できます。

3. 応答フィールドをアサートする

HTTP ステータスが 200 でも、アプリが期待する JSON 形状とは限りません。契約テストとして、最低限次のようなチェックを追加します。

  • status が completed である
  • output[0].content[0].text が存在し、空ではない
  • usage.total_tokens が 0 より大きい
  • tools を指定した場合、output 内に web_search_call などのツール呼び出しアイテムが存在する

例として、確認対象の JSON パスは次のようになります。

status
output[0].content[0].text
usage.total_tokens
output[*].type
Enter fullscreen mode Exit fullscreen mode

Apidog のビジュアルアサーションビルダーを使うと、テストスクリプトを書かずにこれらの JSON パスを検証できます。テストケースの構成例は、API テストケーステンプレートも参考になります。

リクエストをコレクションに保存しておけば、CI で繰り返し実行できるテストとして扱えます。

4. オフライン開発用にレスポンスをモックする

OpenAI の呼び出しには費用がかかり、ネットワーク接続も必要です。UI 開発や CI の一部では、毎回ライブ API を呼びたくないケースがあります。

その場合は、代表的な /v1/responses のレスポンスを Apidog のモックとして保存します。アプリ側の接続先を Apidog のモック URL に向けることで、フロントエンドやテストは同じ JSON 形状をトークン費用なしで利用できます。

モック対象の例です。

{
  "id": "resp_mock_001",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses for development and testing."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}
Enter fullscreen mode Exit fullscreen mode

一般的なモック API の考え方は、モック API の説明でも解説されています。

実運用では、次のように使い分けるのが実装しやすいです。

  • OpenAI との契約検証にはライブエンドポイントを使う
  • UI 開発や CI の高速テストにはモックを使う

どちらも同じ Apidog プロジェクト内で管理できます。

よくある質問

Responses API は Chat Completions を置き換えますか？

強制的に置き換える必要はありません。OpenAI は Responses API を Chat Completions の進化版と位置づけ、新しいプロジェクトに推奨しています。一方で、Chat Completions には非推奨化日が発表されておらず、引き続きサポートされています。

移行する場合は、すべてを一度に書き換えるのではなく、ユーザーフロー単位で段階的に移行できます。

store と previous_response_id の違いは何ですか？

store は、OpenAI がレスポンスオブジェクトを保存するかどうかを制御します。デフォルトは true で、保存されたレスポンスはデフォルトで30日間保持されます。

previous_response_id は、新しいリクエストを保存済みレスポンスに接続するためのフィールドです。これにより、モデルはサーバーサイドで会話を継続できます。

ステートフルな会話では両方を使います。ステートレスにしたい場合は、store を false にします。

Responses API はどのモデルをサポートしていますか？

OpenAI の現在の汎用モデルは Responses API で動作するように設計されていますが、利用可能なモデルはアカウントや設定によって異なります。

実装では、モデル名を固定で決め打ちする前に、OpenAI ダッシュボードで利用可能なモデルを確認してください。Apidog から簡単なリクエストを送信し、レスポンスの model フィールドを見ることで、実際に呼び出せているモデルも確認できます。

コードを書かずに組み込みツールをテストできますか？

はい。Apidog の JSON ボディに tools 配列を追加し、リクエストを送信します。その後、output 配列に web_search_call などのツール呼び出しアイテムが含まれることをアサートします。

SDK を使わず、HTTP レベルで OpenAI の動作を確認できます。エージェントのツール呼び出しをより広くテストする場合は、OpenAPI 仕様から API テストコレクションを生成する方法も参考になります。

まとめ

Responses API では、POST /v1/responses という単一のエンドポイントで、テキスト生成、組み込みツール、サーバーサイドの会話状態を扱えます。

実装時の要点は次のとおりです。

  • model と input を指定してリクエストする
  • 出力テキストは output[0].content[0].text から読む
  • Web 検索やコード実行が必要な場合は tools を追加する
  • 会話を継続する場合は previous_response_id を渡す
  • ステートレスにしたい場合は store: false を指定する
  • 本番統合前にレスポンス形状を契約テストで検証する

Chat Completions とはレスポンス形状が異なるため、古い API の前提で実装しないことが重要です。

Apidog をダウンロードすれば、/v1/responses のリクエスト作成、環境変数でのキー管理、ネストされた output のアサーション、オフライン開発用のモックまで、1つのプロジェクトで実行できます。テストコードを書かずに、Apidog で Responses API の統合を検証できます。

Top comments (0)