Responses API——OpenAI 下一代智能体与多模态 API 完整开发者指南
🧠 OpenAI 下一代智能体与多模态 API 完整开发者指南
Responses API、GPT-5 推理、函数调用、结构化输出与多模态功能深度教程
引言：从聊天到智能体的演进
在人工智能应用开发领域，一场深刻的范式转变正在发生。
我们正在从传统的“请求/响应”模式（以 Chat Completions API 为代表）迁移到一种“默认即智能体”（agentic by default）的全新框架。
这一转变的核心是 Responses API 的推出。它不仅仅是一个新的端点，而是一种全新的 API 原语（API Primitive），为未来的智能体生态奠定了基础。
Responses API 是一个统一的、“面向未来”的（future-proof）基础架构，集成了：
- GPT-5 等模型的推理能力
- 网页搜索等内置工具
- 自定义函数调用
- 有保证的结构化输出
- 原生的多模态（视觉、音频、图像生成）支持
第一部分：新基础 — 掌握 Responses API
1.1 架构变革：从 Chat 到 Responses
| 功能 | Chat Completions API（旧） | Responses API（新） |
|---|---|---|
| 端点 | /v1/chat/completions | /v1/responses |
| 系统提示 | messages: [{"role": "system", ...}] | instructions: "..." |
| 用户输入 | messages: [{"role": "user", ...}] | input: "..." 或 input: [...] |
| 对话状态 | 手动管理 messages 数组 | previous_response_id 或 context |
| 响应字段 | choices.message | output 数组（含 output_text） |
| 结构化输出 | response_format | text.format |
| 多模态 | 支持有限 | 原生支持文本 + 图像 |
1.2 请求结构：更清晰的职责分离
旧方法 (Chat Completions)
系统与用户提示混合在 messages 数组中。
新方法 (Responses)
- 系统提示使用
instructions - 用户输入使用
input input可为字符串或消息数组（兼容旧结构）
1.3 状态管理：对话链与缓存优化
旧模型中，开发者需手动维护整个消息历史，导致高成本与复杂性。
Responses API 新机制：
- 使用
previous_response_id引用上一个响应。 - 服务器端自动加载上下文与缓存。
- 可使用
store: true持久化状态（工具与推理上下文）。
示例：Python 状态链调用
from openai import OpenAI
client = OpenAI()# 第一次请求
response = client.responses.create(model="gpt-4o-mini",input="给我讲个笑话"
)
print(response.output_text)# 第二次请求（引用上一个响应）
second_response = client.responses.create(model="gpt-4o-mini",previous_response_id=response.id,input=[{"role": "user", "content": "解释一下为什么这个笑话好笑。"}]
)
print(second_response.output_text)
优势：
- 成本下降（缓存利用率提升 40%-80%）
- 状态管理自动化
- “默认即智能体”设计理念落地
第二部分：控制新思维 — GPT-5 推理与新参数
GPT-5 引入了新的推理控制逻辑：
从“随机性”转向“计算资源分配”。
旧参数如 temperature、top_p 已不再适用，取而代之的是：
| 控制目标 | 旧参数（GPT-4） | 新参数（GPT-5） |
|---|---|---|
| 创造性 / 随机性 | temperature, top_p | ❌（不支持） |
| 思考深度 | 无 | reasoning.effort |
| 输出简洁度 | 提示控制 | text.verbosity |
| 输出长度 | max_tokens | max_output_tokens |
2.1 推理深度：reasoning.effort
| 选项 | 说明 |
|---|---|
minimal | 极快响应，适合确定性任务 |
low | 快速、低消耗（接近 GPT-4.1） |
medium | 默认值，平衡速度与深度 |
high | 深度推理，适用于复杂任务 |
2.2 输出详略：text.verbosity
| 选项 | 输出特征 |
|---|---|
low | 简洁精炼 |
medium | 平衡默认 |
high | 详细冗长，适合教学或文档 |
可组合控制，例如：
深度推理但简短回答 →
reasoning.effort: "high",text.verbosity: "low"
第三部分：构建智能体工作流 — 工具、函数与结构化数据
3.1 三步函数调用机制
步骤 1：定义工具（Tools）
tools = [{"type": "function","function": {"name": "get_current_weather","description": "获取城市天气","parameters": {"type": "object","properties": {"location": {"type": "string"}},"required": ["location"]}}}
]
步骤 2：模型请求调用工具
模型返回 tool_calls 对象，例如：
{"tool_calls": [{"id": "call_abc123","name": "get_current_weather","arguments": {"location": "San Francisco"}}]
}
步骤 3：执行函数并返回结果
messages.append({"tool_call_id": "call_abc123","role": "tool","name": "get_current_weather","content": '{"temperature": "72", "unit": "fahrenheit"}'
})
3.2 内置工具支持
| 工具 | 功能 |
|---|---|
web_search_preview | 网页搜索 |
code_interpreter | 运行代码 |
file_search | 文件检索 |
computer_use | 计算机控制 |
3.3 结构化输出（Structured Output）
区别于旧的 JSON 格式化输出：
| 模式 | 类型 | 特性 |
|---|---|---|
| JSON 模式 | json_object | 确保有效 JSON，但不保证结构 |
| 结构化输出 | json_schema | 严格模式校验 + 完整字段验证 |
示例：使用 JSON Schema 强制结构化
"text": {"format": {"type": "json_schema","name": "research_paper_extraction","schema": {"type": "object","properties": {"title": {"type": "string"},"authors": {"type": "array", "items": {"type": "string"}},"abstract": {"type": "string"},"keywords": {"type": "array", "items": {"type": "string"}}},"required": ["title", "authors", "abstract", "keywords"],"additionalProperties": false},"strict": true}
}
第四部分：多模态 API — 视觉与图像生成
4.1 视觉输入（Vision）
支持传递多张图像，三种方式：
image_url- Base64 编码
file_id（文件上传后引用）
参数：detail
| 选项 | 说明 |
|---|---|
low | 低分辨率，低成本 |
high | 高分辨率，理解更准确 |
auto | 模型自动决定 |
限制：
- 最大 50MB
- 最多 500 张图像
- 格式：PNG, JPG, WEBP, GIF（非动画）
4.2 图像生成（DALL·E 3 与 GPT-Image-1）
| 参数 | GPT-Image-1 | DALL·E 3 |
|---|---|---|
size | 1024x1024, 1536x1024 等 | 1024x1024, 1792x1024 等 |
quality | low/medium/high | standard / hd |
style | 不适用 | vivid / natural |
| 多张图像 | 支持 | 不支持 |
第五部分：多模态 API — 音频（语音识别与语音合成）
5.1 语音转文本（Speech-to-Text）
| 模型 | 功能 |
|---|---|
gpt-4o-transcribe | 转录音频为原语言 |
whisper-1 | 翻译成英语 |
gpt-4o-transcribe-diarize | 自动标注说话人 |
示例：
from openai import OpenAI
client = OpenAI()
audio = open("/path/to/audio.mp3", "rb")result = client.audio.transcriptions.create(model="gpt-4o-transcribe",file=audio
)
print(result.text)
5.2 文本转语音（Text-to-Speech）
| 模型 | 特点 |
|---|---|
gpt-4o-mini-tts | 可提示语气、情感 |
tts-1 | 低延迟 |
tts-1-hd | 高保真 |
支持声音：alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer 等。
import OpenAI from "openai";
const openai = new OpenAI();const mp3 = await openai.audio.speech.create({model: "gpt-4o-mini-tts",voice: "coral",input: "Hello, world!",instructions: "Speak in a cheerful and positive tone."
});
语音智能体架构
| 架构 | 流程 | 特点 |
|---|---|---|
| 链式 (Chained) | 语音→文本→文本→语音 | 控制性强，延迟高 |
| 语音到语音 (Speech-to-Speech) | 单模型实时音频输入输出 | 自然流畅，低延迟 |
🧩 结论：智能体的时代已来临
一个完整的智能体应用现在可通过 单一的 Responses API 构建：
- 语音输入：
gpt-4o-transcribe转录 - 视觉理解：
gpt-4v分析图像 - 推理决策：
gpt-5高效思考 - 调用函数：
get_current_weather获取实时信息 - 状态引用：通过
previous_response_id管理上下文 - 语音输出：
gpt-4o-mini-tts输出自然语音
简单聊天机器人的时代已经结束。
智能体的时代已经到来。
现在，就开始构建吧。