# Responses API

使用 Responses 格式发送文本请求，了解网关转换、事件格式与状态续接限制。

## 接口定位 [#接口定位]

`POST /v1/responses` 接收 Responses 格式，将输入转换成 Chat Completions 请求，再将助手文本转换为 Responses 输出。它适合使用 Responses 请求形状的文本客户端，但不是完整的上游原生 Responses 服务。


**提示**

当前转换器只把助手文本写入响应 `output`。即使请求接受 `tools`，也不能据此认为支持完整的 `function_call` / `function_call_output` 循环。需要工具回传时使用 [Chat Completions 工具调用](/docs/tool-calls)。


## 端点与输入形式 [#端点与输入形式]

| 项目 | 值 |
| --- | --- |
| 端点 | `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**


```bash
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
  }'
```



**Python**


```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.responses.create(
    model="deepseek-v4-pro",
    instructions="用中文回答，最多三句话。",
    input="为什么生产请求需要超时设置？",
    max_output_tokens=512,
    stream=False,
)

texts = []
for item in response.output:
    if item.type == "message":
        for part in item.content:
            if part.type == "output_text":
                texts.append(part.text)
print("".join(texts))
print("status:", response.status)
print("usage:", response.usage)
```




## 响应字段与事件 [#响应字段与事件]

下面是非流式响应结构示意，不是一次真实调用的返回值：

```json
{
  "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`，不会完整保留推理块和工具事件。最终状态标签不是内容完整性或业务正确性的保证，应用还应检查是否有文本、连接是否完整结束。

## 注意事项与相关文档 [#注意事项与相关文档]

图片与视频模型不能通过此端点调用。部分错误提示会提到兼容视频路径，但新接入应按 [视频生成](/docs/video-generation) 选择正确端点，不要机械地按文本接口替换路径。

接口 `usage` 是返回给客户端的用量字段，平台结算可能经过计数、缓存分类与计费处理；不要直接把 `usage` 当作 元金额。可在 [用量与调用日志](/docs/usage-logs) 核对请求，再阅读 [计费与充值](/docs/billing)。

相关文档：[流式输出](/docs/streaming)、[结构化输出](/docs/structured-output)、[推理模型](/docs/reasoning)、[错误码与重试](/docs/errors)。