OpenAI Responses API 使い方

このガイドでは、OpenAI Responses API のエンドツーエンドでの使用方法を説明します。読み終える頃には、POST /v1/responses へのリクエスト送信、返されるネストされた出力の読み取り、組み込みツールの有効化、呼び出しをまたいだ会話状態の維持、そして Apidog 内での全体的な契約検証ができるようになります。Responses API は、モデル出力を生成するための OpenAI の新しいインターフェースであり、公式のResponsesガイドでは、OpenAI が新しいプロジェクトにこれを推奨する理由が説明されています。もし以前の古いエンドポイントをテストしていたとしても、ChatGPT API テストガイドのワークフローと同様に、その設定のほとんどを再利用できます。

ボタン

まず必要なもの

リクエストを送信する前に、いくつかの項目があることを確認してください。

現在の汎用モデルにアクセスできる OpenAI API キー。キーは、コマンドや共有ファイルに貼り付けるのではなく、環境変数に保管してください。
あなたのアカウントが実際に呼び出せるモデル名。ハードコードするのではなく、OpenAI ダッシュボードのモデルリストを確認し、エンドポイントと照合してください。
生の HTTP リクエストを送信し、返ってくる JSON を検査する方法。最初の呼び出しには curl を備えたターミナルが機能し、後でレスポンスをアサートしたりモックしたりするには Apidog を使用します。

また、呼び出す前にエンドポイントが何をするかを知っておくことも役立ちます。Responses API は、単一のエンドポイント POST /v1/responses を公開しています。モデル名と input を送信すると、プレーンテキスト、関数呼び出し、およびウェブ検索やファイル検索のような OpenAI ホスト型ツールの結果を含む応答オブジェクトが返されます。1回の呼び出しで、モデルがウェブを検索することを決定し、結果を読み込み、回答を書き込むという一連の多段階の処理全体を実行でき、応答はその各ステップを記録します。

プレーンテキストのエンドポイントと Responses API を区別する点が2つあります。1つ目は、サーバーサイドで組み込みツールを実行できるため、独自の検索やサンドボックスを構築する必要がないことです。2つ目は、デフォルトでステートフルであることです。すべての応答には id が与えられ、その id を次のリクエストに渡すことで、OpenAI が会話履歴を保持してくれます。OpenAI は Responses API を Chat Completions の進化版と説明し、Assistants API ベータ版からの教訓を取り入れて、新しいプロジェクトにこれを推奨しています。これにより、3つの異なるメンタルモデルではなく、1つのモデルで対応できるようになります。

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 は引き続きサポートされると述べており、すべてを一度に書き換えるのではなく、一度に1つのユーザーフローを移行できます。Assistants API は期限が迫っており、OpenAI は2025年8月26日に非推奨化を発表し、2026年8月26日に廃止予定であるため、新しいエージェント作業は Responses で開始すべきです。

最初のリクエストを行う

以下は最小限の呼び出し例です。モデル名をあなたのアカウントがアクセスできるものに置き換え、キーはコマンド自体には含めないでください。

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
  }'

ここでは3つの重要なものを渡します。model、input (プロンプト)、そして instructions (システムレベルの指示) です。store を true に設定すると、OpenAI は応答を保存し、後でスレッドを継続できるようにします。

応答を読む

省略された応答は次のようになります。

{
  "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
  }
}

この構造に注目してください。人々が躓きやすい部分だからです。必要なテキストはトップレベルのフィールドではなく、output[0].content[0].text に存在します。公式の SDK は、すべてのテキストアイテムを1つの文字列に集約する output_text という便利なアクセサーを追加していますが、このプロパティは SDK のヘルパーであり、生の HTTP JSON の一部ではありません。エンドポイントを直接呼び出す場合、ネストされたパスを読み取ります。トップレベルの id は状態のために再利用するものであり、usage.total_tokens はその呼び出しにかかったコストを示します。

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

主要な機能は、OpenAI が特定のツールをあなたのために実行することです。これらを tools 配列にリストすると、モデルがいつそれらを呼び出すかを決定します。検証済みの組み込みタイプには以下が含まれます。

引用付きのリアルタイムインターネット検索のための web_search (古い web_search_preview はレガシーな統合ではまだ機能しますが、新しい制御が不足しています)。
アップロードしたファイル全体の検索のための file_search。
サンドボックス内でコードを実行および分析するための code_interpreter。
コンピュータインターフェースを操作するための computer_use。
インラインで画像を生成するための image_generation。

これらを有効にするには、ボディに小さな追加を行うだけです。

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

モデルがツールを使用すると、output 配列には、最終的な message とともに web_search_call アイテムのような、そのステップを文書化するエントリが追加されます。これは後で役立ちます。テキストが返されただけでなく、ツールが実際に起動したことを確認できるためです。

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

状態は2つのパラメータを通じて機能します。store はデフォルトで true であり、OpenAI が応答オブジェクトを保存し (デフォルトで30日間保持されます)、id を返します。その id を次の呼び出しで previous_response_id として渡すと、あなたがトランスクリプトを再送信することなく、モデルはスレッドを継続します。

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

ステートレスにしたい場合、またはデータ保持ゼロの要件がある場合は、store を false に設定し、コンテキストを自分で管理してください。リアルタイム、低遅延の音声およびオーディオフローの場合、OpenAI は別のインターフェースを使用します。GPT リアルタイム API ガイドでそのケースをカバーしています。そして、これらすべての上に多段階エージェントをオーケストレーションしている場合、パターンはOpenAI Agents SDKと一致します。

Apidog でテストする方法

Apidog は、API のテスト、設計、モックのプラットフォームです。OpenAI SDK やコードライブラリではないため、Python でコードを記述することはありません。その代わりに、/v1/responses への生の HTTP リクエストを構築し、送信し、返される JSON に対してアサーションを作成します。これは、ユーザーが気付く前に破損した統合を検出するのに役立つ、まさに契約チェックの種類です。

以下に、セットアップのステップバイステップを示します。

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

Apidog で環境（例：「OpenAI Prod」）を作成し、OPENAI_API_KEY のような変数を追加します。秘密が共有コレクションにコミットされないように、値はリクエスト内ではなく環境に保存してください。次に、https://api.openai.com/v1/responses への新しい POST リクエストを構築し、ヘッダー Authorization: Bearer {{OPENAI_API_KEY}} を追加します。Apidog は送信時に変数を置き換えます。

ボディを JSON に設定し、以前のリクエストを貼り付けます。送信ボタンを押します。ネストされた output 配列を含む、フォーマットされた完全な応答オブジェクトが表示されます。

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

成功した 200 は、応答があなたのアプリが期待する形状であることを証明するものではありません。回帰が loudly 失敗するようにアサーションを追加してください。/v1/responses の応答に対する有用なチェックは次のとおりです。

status が completed と等しい。
output[0].content[0].text が存在し、空ではない。
usage.total_tokens が 0 より大きい。
tools を送信した場合、output 内のアイテムの type が web_search_call と等しい。

Apidog のビジュアルアサーションビルダーを使用すると、テストスクリプトを記述することなくこれらの JSON パスをターゲットにでき、API テストケーステンプレートでは、このようなチェックを構造化する方法が示されています。リクエストをコレクションに保存すると、CI で実行できる繰り返し可能なテストになります。

オフライン開発用の応答をモックする

OpenAI の呼び出しには費用がかかり、ネットワークアクセスが必要です。これは、応答を消費する UI を構築している場合や、有料 API を呼び出すべきではないパイプラインでテストを実行している場合には不便です。Apidog のモック機能がこれを解決します。代表的な /v1/responses ペイロードをモックとして保存し、アプリを Apidog のモック URL に向けます。これにより、フロントエンドはトークン費用なしで正しい JSON 形式を取得できます。実際のAPIが変更された場合でも、すべてのテストで障害を追いかけるのではなく、1つのモックを更新するだけで済みます。モック API の説明では、一般的なアプローチについて解説しています。

この分割は重要です。OpenAI との契約を検証するためにライブエンドポイントに対してテストを行い、高速でオフラインかつ確定的な開発のためにそれをモックします。どちらも同じ Apidog プロジェクトから実行されます。

よくある質問

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

強制的にではありません。OpenAI は Responses を Chat Completions の進化版と呼び、新しいプロジェクトに推奨していますが、Chat Completions は非推奨化日が発表されておらず、引き続きサポートされています。一度に1つのフローを移行できます。Assistants API は、2026年に廃止予定で、リタイア対象となっています。

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

store は、OpenAI が応答オブジェクトを保存するかどうかを制御します（デフォルトは true で、30日間保持されます）。previous_response_id は、新しいリクエストを保存された応答にリンクして、モデルがサーバーサイドで会話を継続する方法です。ステートフルなスレッドではこれらを組み合わせて使用し、ステートレスな動作が必要な場合は store をオフにします。

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

OpenAI の現在の汎用モデルは Responses API で動作するように設計されていますが、利用可能性はあなたのアカウントと選択したモデルによって異なります。モデル名をハードコードするのではなく、OpenAI ダッシュボードのモデルリストを確認し、エンドポイントと照合してください。Apidog を通じて簡単なリクエストを送信し、応答の model フィールドを読むことで、あなたのキーが実際にどのモデルを呼び出せるかを素早く確認できます。

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

はい。Apidog の JSON ボディに tools 配列を追加し、リクエストを送信し、一致するツール呼び出しアイテム (web_search_call など) が output 配列に表示されることをアサートします。HTTP 経由で OpenAI の動作をチェックするため、SDK は必要ありません。エージェントのツール呼び出しをより広範にテストするには、OpenAPI 仕様から API テストコレクションを生成する方法を参照してください。

まとめ

これで、テキスト、ホスト型ツール、サーバーサイドの会話状態を処理する単一のエンドポイント POST /v1/responses を完全に理解しました。リクエストを送信し、ネストされた output を読み取り、検索やコード実行が必要な場合は tools 配列を追加し、スレッドを継続するために previous_response_id を連結します。Chat Completions とは形状が異なるため、古い API の記憶に頼るのではなく、自分で契約を検証することが最も安全な方法です。

そこで Apidog が役立ちます。リクエストを構築し、キーを環境変数として保存し、ネストされた output フィールドをアサートし、オフライン作業のために応答をモックする、これらすべてを1つのプロジェクトで行えます。Apidog をダウンロードして、/v1/responses にテストを向ければ、あなたの統合が正確に何を受け取るかを確認できます。テストコードを一行も書かずに、Apidog ですべてのセットアップを行うことができます。

ボタン