GPT-5.6 Responses API 使用指南 — 新 API 模式完整示例

什么是 Responses API

Responses API 是 OpenAI 为 GPT-5.x 系列（包括 5.6）设计的新一代 API 接口。它取代了传统的 Completions API 和 Chat Completions API，提供更灵活的结构和更强大的新特性：

特性	Chat Completions API	Responses API
输入格式	固定消息列表	灵活的输入项类型
工具调用	手动管理	可编程工具调用
多智能体	❌	✅ 内置
提示词缓存	部分支持	原生、更精准
推理强度	有限选项	完整档位
流式响应	基础	更丰富的事件类型

基础用法

简单文本生成

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-sol",
    input=[
        {
            "role": "system",
            "content": "你是一个资深 Python 工程师，擅长代码审查。"
        },
        {
            "role": "user",
            "content": "帮我审查这段代码"
        }
    ],
    reasoning={
        "effort": "medium"
    }
)

# 直接获取文本
print(response.output_text)

带推理强度

# medium 档位（推荐作为默认）
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[user_input],
    reasoning={"effort": "medium"}
)

# xhigh 档位（复杂任务）
response = client.responses.create(
    model="gpt-5.6-sol",
    input=[complex_task],
    reasoning={"effort": "xhigh"}
)

# max 档位（最复杂任务）
response = client.responses.create(
    model="gpt-5.6-sol",
    input=[hardest_task],
    reasoning={"effort": "max"}
)

# ultra 模式（四智能体并行，Sol 独有）
response = client.responses.create(
    model="gpt-5.6-sol",
    input=[task_for_ultra],
    multi_agent={
        "enabled": True,
        "num_agents": 4,
        "task_strategy": "auto"
    }
)

流式响应

stream = client.responses.stream(
    model="gpt-5.6-sol",
    input=[user_input]
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n[完成]")

多轮对话

Responses API 支持会话管理，可以自动跟踪历史：

# 创建一个会话会话
conversation = client.responses.create(
    model="gpt-5.6-sol",
    input=[first_message],
    store=True  # 自动存储上下文
)

# 继续对话（会自动携带历史）
continuation = client.responses.create(
    model="gpt-5.6-sol",
    previous_response_id=conversation.id,
    input=[second_message]
)

工具调用

基础工具调用

tools = [
    {
        "type": "function",
        "name": "search_database",
        "description": "在数据库中搜索用户",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "搜索关键词"}
            },
            "required": ["query"]
        }
    }
]

response = client.responses.create(
    model="gpt-5.6-terra",
    input=["帮我找一下叫张三的用户"],
    tools=tools
)

# 模型可能返回工具调用请求
for item in response.output:
    if item.type == "function_call":
        # 执行工具调用
        result = my_search_function(item.arguments["query"])
        # 把结果发回去
        result_response = client.responses.create(
            model="gpt-5.6-terra",
            previous_response_id=response.id,
            tool_choice="submit",
            tools=tools,
            # 传递工具结果
        )

可编程工具调用（GPT-5.6 新特性）

# GPT-5.6 可以自主决定什么时候调用工具
# 并在运行中动态调整工作流
response = client.responses.create(
    model="gpt-5.6-sol",
    input=[complex_dev_task],
    tools=[
        run_tests_tool,
        search_code_tool,
        run_shell_tool
    ],
    # 让模型自主协调工具使用
    tool_choice="auto"  # 默认就是 auto
)

联网搜索工具

GPT-5.6 内置了联网搜索能力：

response = client.responses.create(
    model="gpt-5.6-sol",
    input=["GPT-5.6 的最新定价是多少？"],
    tools=[{
        "type": "web_search",
        "search_context_size": "medium"
    }]
)

响应结构详解

{
  "id": "resp_xxxxxxxxxxxxx",
  "model": "gpt-5.6-sol",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "...", "annotations": []}
      ]
    }
  ],
  "usage": {
    "input_tokens": 2100,
    "output_tokens": 850,
    "total_tokens": 2950,
    "cached_input_tokens": 1500  // 缓存命中的 Token
  },
  "reasoning": {
    "effort": "medium",
    "summary": ["思考步骤摘要..."]
  }
}

从 Chat Completions 迁移

如果你之前用过 Chat Completions API，迁移到 Responses API 需要注意：

变化点

Chat Completions	Responses
`client.chat.completions.create()`	`client.responses.create()`
`messages` 参数	`input` 参数
`response.choices[0].message.content`	`response.output_text`
`tool_calls` 手动解析	更结构化的 `output` 列表
没有多智能体	`multi_agent` 参数支持

快速迁移示例

# 旧方式
resp_old = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp_old.choices[0].message.content)

# 新方式（完全等价）
resp_new = client.responses.create(
    model="gpt-5.6-sol",
    input=[{"role": "user", "content": "你好"}]
)
print(resp_new.output_text)

错误处理

常见错误码：

错误码	含义	处理方式
400	请求格式错误	检查 model ID、参数值
401	API Key 无效	检查 key 是否正确
429	速率限制或余额不足	等待、升级限额、充值
500	服务端错误	重试
503	服务暂不可用	稍后重试

最佳实践

默认用 medium 档位：Sol + medium 是性价比的甜点区
启用流式响应：提升用户体验
用 store=True 管理对话：不用手动管理历史
Terra 做日常、Sol 做难题：分层路由控制成本
监控 usage.cached_input_tokens：提示词缓存是否生效