For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション

Responses API への移行

Responses API は、Chat Completions を進化させた新しい API の基盤です。連携をよりシンプルにし、エージェント型アプリケーションの構築に役立つ強力な基本機能を提供します。

Chat Completions のサポートは継続しますが、新規プロジェクトにはすべて Responses を推奨します。

Responses API の概要

Responses API は、エージェントのように動作する強力なアプリケーションを構築するための統一インターフェースです。次の機能を備えています。

Responses のメリット

Responses API には、Chat Completions と比べて次のようなメリットがあります。

  • 性能の向上:GPT-5 などのリーズニングモデルを Responses で使用すると、Chat Completions よりもモデルの能力を引き出せます。社内評価では、同じプロンプトと設定で SWE-bench のスコアが 3% 向上しました。
  • エージェント動作を標準でサポート:Responses API はエージェントの実行ループとして機能し、モデルは 1 回の API リクエスト内で、web_searchimage_generationfile_searchcode_interpreter、リモート MCP サーバーなどの複数のツールや、独自のカスタム関数を呼び出せます。
  • コストの削減:キャッシュの活用効率が向上することで、コストを削減できます。社内テストでは、Chat Completions と比べてキャッシュの活用効率が 40%~80% 向上しました。
  • ステートフルなコンテキストstore: true を使用すると、ターン間で状態を維持し、推論とツールのコンテキストを引き継げます。
  • 柔軟な入力:input には文字列またはメッセージのリストを渡せます。システムレベルの指示には instructions を使用します。
  • 暗号化された推論:状態の保持を無効にしても、高度な推論を活用できます。
  • 将来を見据えた設計:今後登場するモデルへの対応を見据えて設計されています。
できることChat Completions APIResponses API
テキスト生成
音声近日公開
画像認識
構造化出力
Function Calling
ウェブ検索
ファイル検索
コンピューターの使用
Code Interpreter
MCP
画像生成
推論の要約

具体的なシナリオで、Responses API と Chat Completions API の違いを確認します。

メッセージとアイテムの違い

どちらの API でも、OpenAI のモデルから簡単に出力を生成できます。Chat Completions の呼び出しでは、入力と結果に メッセージの配列を使用します。 一方、Responses API では アイテムを使用します。アイテムは複数の型のユニオンであり、モデルが実行できるさまざまなアクションを表します。 message はアイテムの型の一つで、function_callfunction_call_output も同様です。 Chat Completions のメッセージが多くの役割を一つのオブジェクトにまとめているのに対し、アイテムは役割ごとに分かれており、モデルのコンテキストの基本単位をより適切に表現します。

また、Chat Completions では、n パラメーターを使用して複数の出力を並列に生成し、choices として返すことができます。Responses ではこのパラメーターを廃止し、生成する出力を一つに限定しています。

Chat Completions API
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)
Responses API
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Responses API から返されるレスポンスでは、フィールドが少し異なります。 message の代わりに、固有の id を持つ、型付きの response オブジェクトが返されます。 Responses のレスポンスはデフォルトで保存されます。Chat Completions のレスポンスは、新しいアカウントではデフォルトで保存されます。 どちらの API でも、保存を無効にするには store: false を設定します。

これらの API から返されるオブジェクトには、わずかな違いがあります。 Chat Completions では、各要素に message を含む choices 配列が返されます。Responses では、output という名前のアイテム配列が返されます。

Chat Completions API
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Under a blanket of starlight, a sleepy unicorn tiptoed through moonlit meadows, gathering dreams like dew to tuck beneath its silver mane until morning.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  ...
}
Responses API
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_68af4030baa48193b0b43b4c2a176a1a05438e46b5f69a3b",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_68af40337e58819392e935fb404414d005438e46b5f69a3b",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Under a quilt of moonlight, a drowsy unicorn wandered through quiet meadows, brushing blossoms with her glowing horn so they sighed soft lullabies that carried every dreamer gently to sleep."
        }
      ],
      "role": "assistant"
    }
  ],
  ...
}

その他の違い

  • Responses のレスポンスはデフォルトで保存されます。Chat Completions のレスポンスは、新しいアカウントではデフォルトで保存されます。どちらの API でも、保存を無効にするには store: false を設定します。
  • Responses API ではツールの活用が改善されているため、リーズニングモデルをより効果的に利用できます。GPT-5.4 以降、Chat Completions では reasoning_effortnone 以外の値の場合、ツール呼び出しはサポートされません。
  • 構造化出力の API 形式が異なります。Responses では response_format の代わりに text.format を使用します。詳しくは、構造化出力ガイドをご覧ください。
  • Function Calling の API 形式は、リクエスト内の関数設定と、レスポンスで返される関数呼び出しの両方で異なります。違いの詳細については、Function Calling ガイドをご覧ください。
  • Responses SDK には、Chat Completions SDK にはない output_text ヘルパーがあります。
  • Chat Completions では、会話の状態を手動で管理する必要があります。Responses API では、永続的な会話を扱う Conversations API を利用できます。また、previous_response_id を渡すことで、レスポンスを簡単につなげることもできます。

Chat Completions からの移行

移行は、互いに関連する三つの変更として捉えてください。リクエストの送信先を /v1/responses に変更し、型付きの output 配列から出力を読み取り、アプリケーションでターン間の状態を引き継ぐ方法を選びます。

1. 生成エンドポイントの更新

まず、生成エンドポイントを post /v1/chat/completions から post /v1/responses に変更します。

関数やマルチモーダル入力を使用していない場合、シンプルなメッセージ入力は両方の API で互換性があります。

シンプルなメッセージ入力の再利用
const context = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: context,
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: context,
});

Chat Completions では、messages 配列を作成し、 completion.choices[0].message.content からモデルのテキストを読み取ります。
モデルによるテキスト生成
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});
console.log(completion.choices[0].message.content);

2. メッセージからアイテムへの対応付け

Chat Completions は、入力と出力の両方に messages を使用します。Responses は、型付きアイテムの配列である inputoutput を使用します。message はアイテムの型の 1 つで、ほかにも reasoningfunction_callfunction_call_output などがあります。

Chat Completions の概念Responses での対応
messages[]文字列または入力アイテムの配列として指定する input
システムまたは開発者からの指示トップレベルの instructions、または既存の会話履歴を保持する必要がある場合は互換性のあるメッセージアイテム
ユーザーメッセージrole: "user" を持つ入力メッセージアイテム
アシスタントメッセージresponse.output 内の出力メッセージアイテム。状態を手動で管理する場合は、input に含めて再度渡します。
ツールまたは関数の呼び出しfunction_call 型の出力アイテム
ツールまたは関数の結果call_id で呼び出しと関連付けられた function_call_output 型の入力アイテム
n による複数候補の生成Responses では利用できません。複数の出力候補が必要な場合は、リクエストを個別に送信します。

最終的なテキストだけが必要な場合は、SDK の output_text ヘルパーを使用します。処理フローで推論、ツール、またはマルチモーダル出力を使用する場合は、response.output を反復処理し、各アイテムをその type に応じて処理します。

3. 複数ターンの会話の更新

アプリケーションで複数ターンの会話を扱う場合は、コンテキストの管理ロジックを更新します。Responses には、一般的な状態管理の方法が 3 つあります。

  • 以前のレスポンスのコンテキストを OpenAI に管理させたい場合は、previous_response_id を使用します。previous_response_id は前のレスポンスのトップレベルの instructions を引き継がないため、共通の instructions をリクエストごとに再送信してください。
  • コンテキストを自分で管理したり削減したりする必要がある場合は、以前の output アイテムを次のリクエストに含めて再度渡します。
  • 永続的な会話オブジェクトが必要な場合は、Conversations API を使用します。

Chat Completions では、会話履歴を保存し、 蓄積した messages 配列をリクエストごとに送信します。
複数ターンの会話
let messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is the capital of France?" },
];
const res1 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

messages = messages.concat([res1.choices[0].message]);
messages.push({ role: "user", content: "And its population?" });

const res2 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

previous_response_id を使用する場合でも、連鎖するレスポンスに含まれる過去のすべての入力トークンは、API の入力トークンとして課金されます。

4. 状態を保持する場面の判断

Responses のレスポンスはデフォルトで保存されます。Chat Completions のレスポンスも、新しいアカウントではデフォルトで保存されます。どちらの API でも、保存を無効にするには store: false を設定します。

ゼロデータ保持(ZDR)が要件となっている組織などでは、コンプライアンスやデータ保持ポリシーにより、Responses API をステートフルに使用できない場合があります。こうしたケースに対応するため、OpenAI は暗号化された推論アイテムを提供しています。これにより、ワークフローをステートレスに保ちながら、推論アイテムの利点を活用できます。

状態の保持を無効にしながら推論を活用するには、次の手順に従います。

  • store フィールドstore: false を設定します。
  • 返されたすべての推論アイテムを保持し、再送信します。レスポンスを作成すると、各アイテムにはデフォルトで encrypted_content が含まれます。

すると API は暗号化された推論トークンを返します。これらは通常の推論アイテムと同じように、後続のリクエストで再度渡せます。 ZDR を利用する組織には、OpenAI が store: false を自動的に強制適用します。リクエストに encrypted_content が含まれている場合、その内容はメモリ内で復号され、次のレスポンスの生成に使用された後、安全に破棄されます。新たな推論トークンはすべて直ちに暗号化されて返されるため、中間状態は永続化されません。

5. 関数定義と出力の更新

Chat Completions と Responses の関数の定義方法には、小さいながらも注意すべき違いが 2 つあります。

  1. Chat Completions では、関数定義のタグは外部に配置されます。Responses では、内部に配置されます。
  2. Chat Completions では、関数はデフォルトで非厳密モードです。Responses では、strict を省略すると厳密モードの適用を試みます。スキーマを厳密モードに適合させられない場合は、非厳密モードのベストエフォート型 Function Calling にフォールバックし、解決後のツールを strict: false とともに返します。Responses で非厳密モードの動作を明示的に維持するには、strict: false を設定します。

右側の Responses API の関数の例は、左側の Chat Completions の例と機能的に同等です。

Chat Completions API
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "location"
      ]
    }
  }
}
Responses API
{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location"
    ]
  }
}

Function Calling のベストプラクティス

Responses では、ツール呼び出しとその出力はそれぞれ別の種類のアイテムで、call_id を使って関連付けられます。 Responses での Function Calling の仕組みについて詳しくは、Function Calling のドキュメントをご覧ください。

6. 構造化出力の定義の更新

Responses API では、構造化出力の定義が response_format から text.format に移動しました。

構造化出力
const completion = await openai.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "user",
      content: "Jane, 54 years old",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            minLength: 1,
          },
          age: {
            type: "number",
            minimum: 0,
            maximum: 130,
          },
        },
        required: ["name", "age"],
        additionalProperties: false,
      },
    },
  },
  reasoning_effort: "medium",
});

7. ストリーミングの受信処理の更新

Chat Completions のストリーミングでは、delta フィールドを含むチャンクが逐次返されます。Responses のストリーミングでは、型付きのサーバー送信イベントを使用します。各イベントの type に応じて処理を分岐し、UI やオーケストレーション層に必要なイベントを処理するよう、ストリームの受信処理を更新してください。

テキストのストリーミングでは、次のようなイベントを受信して処理します。

  • response.created
  • response.output_text.delta
  • response.completed
  • error

Function Calling のストリームでも、response.function_call_arguments.deltaresponse.function_call_arguments.done などのイベントが発生することがあります。Responses のストリーミングガイドResponses のストリーミングイベントのリファレンスをご覧ください。

8. ネイティブツールへの移行

アプリケーションに OpenAI のネイティブツールが役立つユースケースがある場合は、ツール呼び出しを更新することで、OpenAI のツールをそのまま利用できます。

Chat Completions では、OpenAI がホストするツールをネイティブに利用できないため、 ツール連携を自分で実装する必要があります。 GPT-6 Astra でツールを呼び出すには Responses API が必要なため、 この例では GPT-5.6 を使用しています。
ウェブ検索ツール
async function web_search(query) {
  const res = await fetch(`https://api.example.com/search?q=${query}`);
  const data = await res.json();
  return data.results;
}

const completion = await client.chat.completions.create({
  model: "gpt-5.6",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who is the current president of France?" },
  ],
  functions: [
    {
      name: "web_search",
      description: "Search the web for information",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  ],
});

9. 移行時によくある誤りの確認

コードを Chat Completions から Responses に移行する際は、次のような問題に注意してください。

  • response.output_textresponse.output ではなく、choices[0].message.content を読み取ってしまうこと
  • output のすべての要素をメッセージとして扱ってしまうこと。推論、ツール呼び出し、関数呼び出しは、それぞれ別の種類のアイテムです。
  • コンテキストを次のレスポンスに手動で引き継ぐ際に、推論、関数呼び出し、関数呼び出しの出力のアイテムを省いてしまうこと
  • 対応する call_id を含めずに関数の結果を送信してしまうこと
  • Responses のリクエストで、text.format ではなく response_format を使用してしまうこと
  • Responses の型付きイベントに対応せずに、Chat Completions のストリーミングチャンク用ハンドラーを再利用してしまうこと
  • previous_response_id を使うと過去のコンテキストへの課金がなくなると思い込んでしまうこと。レスポンスチェーン内の過去の入力トークンは、引き続き入力トークンとして課金されます。

段階的な導入のチェックリスト

Chat Completions は引き続きサポートされるため、ユーザーフローを 1 つずつ移行できます。

  • シンプルなテキスト生成フローから始めます。
  • エンドポイント、リクエストボディ、出力処理を更新します。
  • フローで previous_response_id、アイテムの手動再送、Conversations API のどれを使うかを決めます。
  • フローがステートレス、または ZDR を適用している場合は、store: false を追加します。推論のコンテキストをターン間で引き継ぐ必要がある場合は、暗号化された推論アイテムも含めます。
  • 関数定義を移行し、関数呼び出しの出力に正しい call_id が含まれていることを確認します。
  • 構造化出力のスキーマを response_format から text.format に移動します。
  • Responses の型付きイベントに対応するよう、ストリーミングの受信処理を更新します。
  • ワークフローに適した箇所では、独自のオーケストレーションを OpenAI がホストするツールに置き換えます。
  • Responses に振り向けるトラフィックを増やす前に、動作、レイテンシ、トークン使用量、エラーを比較します。

OpenAI の最新機能や改善を活用できるよう、すべてのフローを段階的に Responses API へ移行することをおすすめします。

Assistants API

Assistants API ベータ版に対する開発者のフィードバックをもとに、Responses API に主要な改善を取り入れ、柔軟性、速度、使いやすさを向上させました。Responses API は、OpenAI でエージェントを構築するための今後の方向性を示すものです。

Assistants API は 2026 年 8 月 26 日に正式に提供を終了し、現在は利用できません。移行ガイドに従って、連携先を Responses API に更新してください。