Responses API
使用 Responses 格式发送文本请求，了解网关转换、事件格式与状态续接限制。
接口定位
POST /v1/responses 接收 Responses 格式，将输入转换成 Chat Completions 请求，再将助手文本转换为 Responses 输出。它适合使用 Responses 请求形状的文本客户端，但不是完整的上游原生 Responses 服务。
当前转换器只把助手文本写入响应 output。即使请求接受 tools，也不能据此认为支持完整的 function_call / function_call_output 循环。需要工具回传时使用 Chat Completions 工具调用。
端点与输入形式
| 项目 | 值 |
|---|---|
| 端点 | POST https://api.gfw.net/v1/responses |
OpenAI SDK base_url | https://api.gfw.net/v1 |
| 鉴权 | Authorization: Bearer $GFW_API_KEY |
| 请求格式 | JSON |
文本 input 可以是字符串，也可以是带 role 与 content 的消息数组。instructions 转成一条 system 消息。多轮对话应由应用把所需历史显式放入 input。
转换器还处理 input_text、input_image 内容块；视觉输入要求模型支持视觉，图片应为 Base64 Data URI。不要把未知类型的输入项当成网关一定会转发的内容。
请求参数与转换
| 字段 | 类型 | 必填 | 当前处理方式 |
|---|---|---|---|
model | string | 是 | GFW 模型 ID |
input | string / array | 常规请求是 | 转成 user 消息或消息列表；示例始终显式提供 |
instructions | string | 否 | 加到消息列表开头，作为 system 文本 |
max_output_tokens | integer | 否 | 转成 Chat Completions 的 max_tokens |
max_tokens | integer | 否 | 兼容字段；若与上一字段同时存在，它会覆盖转换后的值，建议只用 max_output_tokens |
temperature、top_p | number | 否 | 透传，模型需支持 |
stream | boolean | 否 | true 时输出 Responses 命名 SSE 事件 |
response_format | object | 否 | 透传至 Chat Completions；不等同于支持原生 text.format |
reasoning、reasoning_effort | object / string | 否 | 透传；具体取值与行为依赖模型及通道 |
tools、tool_choice、parallel_tool_calls | array / string / object / boolean | 否 | 请求透传，但响应转换未实现完整工具项，不能用作完整工具循环 |
metadata、store | object / boolean | 否 | 透传字段，不构成平台持久化或检索响应的承诺 |
当前转换路径不读取 previous_response_id 来恢复会话，也不处理原生 function_call_output 项。不要仅携带前次响应 ID 省略上下文；不要假定存在响应检索、删除、后台任务或内置网页搜索端点。
完整调用示例
设置环境变量 GFW_API_KEY。Python 依赖 openai 包。以下演示无状态、非流式的文本请求。
curl --fail-with-body --silent --show-error \
--max-time 120 \
https://api.gfw.net/v1/responses \
-H "Authorization: Bearer ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
-H 'Content-Type: application/json' \
--data '{
"model": "deepseek-v4-pro",
"instructions": "用中文回答，最多三句话。",
"input": "为什么生产请求需要超时设置？",
"max_output_tokens": 512,
"stream": false
}'响应字段与事件
下面是非流式响应结构示意，不是一次真实调用的返回值：
{
"id": "resp_chatcmpl_example",
"object": "response",
"created": 1800000000,
"model": "deepseek-v4-pro",
"status": "completed",
"output": [
{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "超时让应用能够明确结束等待。"}]}
],
"usage": {"input_tokens": 30, "output_tokens": 18, "total_tokens": 48}
}| 字段 / 事件 | 说明 |
|---|---|
output[].content[].text | 在 type=output_text 的内容块中读取文本 |
status | 非流式转换将上游 finish_reason=length 映射为 incomplete，其他普通结束映射为 completed |
created | 当前非流式转换器输出此字段，不要强依赖其他原生 Responses 时间字段 |
usage.input_tokens、output_tokens | 输入、输出用量；明细由网关转换，不是金额 |
response.created、response.in_progress | 流式开始与进行中事件 |
response.output_text.delta | 流式文本增量，在 delta 读取 |
response.output_text.done、response.completed | 文本结束与最终响应事件 |
流式桥接主要提取上游 delta.content，不会完整保留推理块和工具事件。最终状态标签不是内容完整性或业务正确性的保证，应用还应检查是否有文本、连接是否完整结束。
注意事项与相关文档
图片与视频模型不能通过此端点调用。部分错误提示会提到兼容视频路径，但新接入应按 视频生成 选择正确端点，不要机械地按文本接口替换路径。
接口 usage 是返回给客户端的用量字段，平台结算可能经过计数、缓存分类与计费处理；不要直接把 usage 当作 元金额。可在 用量与调用日志 核对请求，再阅读 计费与充值。