Skip to Content

Responses API (推荐)

创建模型响应。支持文本和图像输入,生成文本或 JSON 输出。支持函数调用(Tool Calling)、流式响应和多轮对话。

推荐新项目使用 Responses API。 这是 OpenAI 推出的新一代 API,相比 Chat Completions 具备以下优势:

  • 原生 Prompt Cachinginstructionsinput 分离,系统指令自动作为缓存前缀,多轮对话中不变的前缀部分缓存命中率更高,可节省最高 50% 输入 token 费用,同时降低延迟
  • 结构化 item 模式 — 输入/输出格式更清晰,原生支持工具调用流程
  • 更丰富的流式事件 — 细粒度的 SSE 事件类型,便于实时 UI 渲染

端点

POST https://api.ofox.ai/v1/responses

请求参数

参数类型必填说明
modelstring模型标识符,如 openai/gpt-5.2
inputstring | array输入内容,可以是纯文本字符串或结构化消息数组
instructionsstring系统指令(独立于 input,自动享受 Prompt Caching)
streamboolean是否启用 SSE 流式响应,默认 false
max_output_tokensnumber最大生成 token 数
temperaturenumber采样温度 0-2,默认 1
top_pnumber核采样参数
toolsarray可用工具定义(Function Calling)
tool_choicestring | object工具选择策略:autonone 或指定工具
truncationstring截断策略:auto 自动截断 / disabled 超限报错(默认)
textobject文本生成格式配置
storeboolean是否存储响应(默认 true
metadataobject自定义元数据键值对
providerobjectOfoxAI 扩展:路由和回退配置

Input 格式

input 支持两种格式:

1. 简单字符串 — 直接传入文本

{ "input": "你好,请介绍一下自己" }

2. 结构化消息数组 — 多轮对话和多模态输入

interface InputItem { type: 'message' role: 'user' | 'assistant' content: ContentPart[] id?: string // assistant 消息必填 status?: 'completed' // assistant 消息必填 } type ContentPart = | { type: 'input_text'; text: string } // 用户文本输入 | { type: 'input_image'; image_url: string } // 图像输入 | { type: 'output_text'; text: string; annotations?: any[] } // 助手文本输出

在多轮对话中包含 assistant 角色消息时,idstatus 字段为必填。 Responses API 为无状态设计,每次请求需携带完整对话历史。

请求示例

Terminal
curl https://api.ofox.ai/v1/responses \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.2", "input": "解释什么是 API Gateway", "instructions": "你是一个有帮助的技术助手,用中文回答。", "max_output_tokens": 1024 }'

响应格式

{ "id": "resp_abc123", "object": "response", "created_at": 1703123456, "model": "openai/gpt-5.2", "status": "completed", "output": [ { "type": "message", "id": "msg_def456", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "API Gateway(API 网关)是一个...", "annotations": [] } ] } ], "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 } }

响应字段说明

字段类型说明
idstring响应唯一标识符,以 resp_ 开头
objectstring固定值 "response"
created_atnumber创建时间戳(Unix 秒)
modelstring实际使用的模型 ID
statusstring响应状态:completedfailedin_progresscancelled
outputarray输出 item 数组,包含消息和工具调用
usageobjectToken 用量统计

结构化消息输入

使用结构化消息数组实现多轮对话:

multi_turn.py
response = client.responses.create( model="openai/gpt-5.2", input=[ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "法国的首都是哪里?"} ] }, { "type": "message", "role": "assistant", "id": "msg_abc123", "status": "completed", "content": [ {"type": "output_text", "text": "法国的首都是巴黎。", "annotations": []} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "那里有多少人口?"} ] } ] ) print(response.output_text)

流式响应

设置 stream: true 启用 SSE 流式响应:

stream.py
stream = client.responses.create( model="openai/gpt-5.2", input="讲一个关于编程的笑话", stream=True ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True)

流式事件类型

流式响应通过 SSE 发送以下事件:

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}} data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}} data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"你"} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"好"} data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"你好..."}]}} data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}} data: [DONE]
事件类型说明
response.created响应对象创建
response.output_item.added新增输出 item
response.content_part.added新增内容片段
response.output_text.delta文本增量(逐 token 输出)
response.output_item.done输出 item 完成
response.completed响应全部完成
response.function_call_arguments.delta函数调用参数增量
response.function_call_arguments.done函数调用参数完成

Function Calling

Responses API 原生支持工具调用:

tools.py
response = client.responses.create( model="openai/gpt-5.2", input="北京今天天气怎么样?", tools=[ { "type": "function", "name": "get_weather", "description": "获取指定城市的当前天气", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称,如 北京" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } ], tool_choice="auto" ) # 处理工具调用 for item in response.output: if item.type == "function_call": print(f"调用函数: {item.name}") print(f"参数: {item.arguments}")

工具调用响应格式

当模型调用工具时,output 中包含 function_call 类型的 item:

{ "id": "resp_abc123", "object": "response", "status": "completed", "output": [ { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"北京\",\"unit\":\"celsius\"}" } ], "usage": { "input_tokens": 45, "output_tokens": 25, "total_tokens": 70 } }

提交工具结果

将工具执行结果回传给模型,在 input 中包含完整的调用链:

# 第二次请求:提交工具结果 response = client.responses.create( model="openai/gpt-5.2", input=[ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "北京今天天气怎么样?"}] }, { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"北京\",\"unit\":\"celsius\"}" }, { "type": "function_call_output", "id": "fco_abc123", "call_id": "call_xyz789", "output": "{\"temperature\":\"22°C\",\"condition\":\"\"}" } ] ) print(response.output_text) # => "北京今天天气晴朗,气温 22°C,非常适合户外活动。"

Tool Choice 选项

说明
"auto"模型自行决定是否调用工具(默认)
"none"禁止调用工具
{"type": "function", "name": "tool_name"}强制调用指定工具

与 Chat Completions 的对比

特性Chat CompletionsResponses API
端点/v1/chat/completions/v1/responses
输入格式messages 数组input 字符串或结构化 item 数组
系统指令role: "system" messageinstructions 参数(独立缓存)
Prompt Caching系统指令混在 messages 中,缓存前缀不稳定instructions 独立传递,自动缓存,命中率更高
输出格式choices[0].message.contentoutput[0].content[0].textoutput_text
工具调用tool_calls 在 message 中独立的 function_call output item
工具结果role: "tool" messagefunction_call_output input item
流式事件chat.completion.chunk结构化事件类型(response.*
Token 字段prompt_tokens / completion_tokensinput_tokens / output_tokens

两个 API 均可用于生产环境。如果你已有 Chat Completions 集成,无需迁移。 推荐新项目使用 Responses API,尤其是需要复杂工具调用流程或高频调用(可充分利用缓存降低成本)的场景。 详见 函数调用指南

Last updated on