在 OpenAI 的生态系统中，开发者可以通过两种主要API与模型进行交互：Responses API和Chat Completions API。.本教程将深入探讨
这两者之间的区别、适用场景以及如何选择最适合您项目需求的API。

部分OpenAI模型仅支持Response格式，例如o3-pro，codex-mini-latest

基础 API

/v1/responses 请求端点介绍

问问API 全面支持 OpenAI 最新的 Responses API，这是 2025年3月推出的新一代智能体构建接口。Responses API 结合了 Chat Completions 的简洁性与 Assistants API 的工具使用和状态管理能力，为开发者提供更灵活、更强大的AI应用构建体验。

新一代API：Responses API 是 Chat Completions 的超集，提供 Chat Completions 功能的同时，还支持内置工具、状态管理等高级特性。—— 但是它仅支持少数新的 OpenAI 模型，具体请看下文。

🚀 核心特性

• 内置工具支持
• Web搜索、文件搜索、代码解释器、函数调用等丰富工具
• 状态管理
• 通过 previous_response_id 维护对话上下文和状态
• 推理保持
• O3/O4-mini 推理模型的推理令牌在请求间保持连续
• 完全兼容
• 支持所有支持工具的 GPT-4.1、O3系列模型

📋 支持的模型

推理模型（推荐）

• O3 系列：o3, o3-pro, o4-mini
• 特色：推理令牌跨请求保持，提供更智能的上下文理解

对话模型

• GPT-4.1 系列：gpt-4.1, gpt-4.1-mini
• 特色：强大的工具调用和多模态能力
• 模型要求：只有较新的模型才支持 /v1/responses 端点。旧模型如 GPT-3.5 不支持此接口。

🔧 基础用法

简单对话

cURL

curl https://api.wenwen-ai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": "Hello! How can you help me today?",
    "instructions": "You are a helpful assistant."
  }'

Python

Node.js

实际响应示例

基于您的测试结果，以下是完整的响应格式：

{
  "id": "resp_6884fcab4930819dbbc02f15cbe63f6c0a92c38ff214d10a",
  "object": "response",
  "created_at": 1753545899,
  "status": "completed",
  "background": false,
  "error": null,
  "incomplete_details": null,
  "instructions": "You are a helpful assistant.",
  "max_output_tokens": null,
  "max_tool_calls": null,
  "model": "gpt-4.1-2025-04-14",
  "output": [
    {
      "id": "msg_6884fcab8f18819dbcdf349f01b424f80a92c38ff214d10a",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Hello! How can I assist you today?"
        }
      ],
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 10,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 29
  },
  "user": null,
  "metadata": {}
}

📊 请求参数详解

必需参数

参数	类型	说明
model	string	模型名称，如 gpt-4.1, o3
input	string	用户输入内容

可选参数

参数	类型	默认值	说明
instructions	string	null	系统指令，定义助手行为
previous_response_id	string	null	上一个响应的 ID，用于维护上下文
temperature	float	1.0	控制输出随机性 (0-2)
max_output_tokens	int	null	最大输出令牌数
tools	array	[]	可用工具列表
tool_choice	string	"auto"	工具选择策略
parallel_tool_calls	boolean	true	是否允许并行工具调用
store	boolean	true	是否存储对话用于训练
metadata	object	{}	自定义元数据

🛠️ 内置工具支持

1. 函数调用

2. 代码解释器

3. 文件搜索

🔄 状态管理

维护对话上下文

第一轮对话

第二轮对话 - 使用 previous_response_id 维护上下文

多轮工具调用

📈 推理模型特性

O3/O4-mini 推理保持

推理模型在 Responses API 中具有特殊优势：

使用 O3 进行复杂推理

查看推理过程

继续对话，推理上下文会保持

🆚 与 Chat Completions 对比

特性	Chat Completions	Responses API
基础对话	✅ 支持	✅ 支持
流式响应	✅ 支持	✅ 支持
函数调用	✅ 支持	✅ 增强支持
内置工具	❌ 不支持	✅ 丰富工具
状态管理	❌ 无状态	✅ 有状态
推理保持	❌ 不支持	✅ O3/O4支持
文件搜索	❌ 不支持	✅ 支持
代码解释器	❌ 不支持	✅ 支持

迁移示例

从 Chat Completions 迁移到 Responses API：

旧方式（Chat Completions）

新方式（Responses API）

🔧 高级功能

并行工具调用

输出格式控制

推理努力控制（O3系列）

📊 响应字段详解

核心字段

字段	类型	说明
id	string	响应唯一标识符
object	string	固定为 "response"
created_at	integer	创建时间戳
status	string	状态：completed/failed/in_progress
model	string	实际使用的模型版本
output	array	输出消息数组
usage	object	Token 使用统计

输出消息格式

{
  "id": "msg_xxx",
  "type": "message",
  "status": "completed",
  "content": [
    {
      "type": "output_text",
      "text": "响应内容",
      "annotations": [],
      "logprobs": []
    }
  ],
  "role": "assistant"
}

使用统计

{
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 10,
    "output_tokens_details": {
      "reasoning_tokens": 0  // 仅推理模型
    },
    "total_tokens": 29
  }
}

🚨 错误处理

标准错误格式

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_supported",
    "message": "The model 'gpt-3.5-turbo' is not supported for the responses endpoint.",
    "param": "model"
  }
}

常见错误

错误码	说明	解决方案
model_not_supported	模型不支持 Responses API	使用支持的新模型
invalid_previous_response_id	无效的上一个响应ID	检查响应ID是否正确
tool_not_available	工具不可用	检查工具配置
max_tokens_exceeded	超出令牌限制	减少输入或设置max_output_tokens

💡 最佳实践

1. 状态管理策略

2. 工具调用优化

3. 推理模型优化

🔮 未来发展

即将推出的功能

• 完整的 Assistants API 功能集成（2026年上半年）
• 更多内置工具：Web搜索、计算机使用等
• 模型上下文协议 (MCP) 支持
• 增强的多模态能力

迁移时间线

• 现在：可以开始使用 Responses API
• 2026年上半年：功能对等 Assistants API
• 2026年：Assistants API 弃用公告
• 2027年：完全迁移到 Responses API

官方文档入口：https://platform.openai.com/docs/guides/responses-vs-chat-completions

Responses API 接口使用指南

基础 API#

/v1/responses 请求端点 介绍#

🚀 核心特性#

📋 支持的模型#

推理模型（推荐）#

对话模型#

🔧 基础用法#

简单对话#

cURL#

Python#

Node.js#

实际响应示例#

📊 请求参数详解#

必需参数#

可选参数#

🛠️ 内置工具支持#

1. 函数调用#

2. 代码解释器#

3. 文件搜索#

🔄 状态管理#

维护对话上下文#

第一轮对话#

第二轮对话 - 使用 previous_response_id 维护上下文#

多轮工具调用#

📈 推理模型特性#

O3/O4-mini 推理保持#

使用 O3 进行复杂推理#

查看推理过程#

继续对话，推理上下文会保持#

🆚 与 Chat Completions 对比#

迁移示例#

旧方式（Chat Completions）#

新方式（Responses API）#

🔧 高级功能#

并行工具调用#

输出格式控制#

推理努力控制（O3系列）#

📊 响应字段详解#

核心字段#

输出消息格式#

使用统计#

🚨 错误处理#

标准错误格式#

常见错误#

💡 最佳实践#

1. 状态管理策略#

2. 工具调用优化#

3. 推理模型优化#

🔮 未来发展#

即将推出的功能#

迁移时间线#