OpenAI 兼容 API
使用 Chat Completions 接口完成对话，了解参数、SDK 地址与协议兼容边界。
适用场景
Chat Completions 是多轮对话的基本接口。应用提交本轮问题及需要保留的历史消息，读取助手回复，再把回复加入下一轮历史。对话历史由应用维护，不会因为复用 API Key 自动关联。
本文以 GFW 模型 ID deepseek-v4-pro 演示。请先在 模型库 确认模型仍可用、账号有权访问；模型 ID 不应添加上游厂商名称或路径前缀。示例用于展示请求格式，响应示意不是实测结果。
端点与鉴权
| 项目 | 值 |
|---|---|
| 对话请求 | POST https://api.gfw.net/v1/chat/completions |
SDK base_url | https://api.gfw.net/v1 |
| 鉴权 | Authorization: Bearer $GFW_API_KEY |
| 请求格式 | Content-Type: application/json |
| 旧式文本补全 | POST /v1/completions |
/v1/completions 使用 prompt 而不是 messages，返回内容通常从 choices[].text 读取。端点存在不代表所有对话模型支持旧式补全；新应用优先使用 Chat Completions。控制台登录 Token 不能替代模型 API Key。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | GFW 模型 ID，例如 deepseek-v4-pro |
messages | array | 是 | 非空消息列表；基础文本消息包含 role 和 content |
messages[].role | string | 是 | 常用 system、user、assistant；工具交互还使用 tool |
messages[].content | string | 文本消息是 | 消息文本；多模态和工具消息有不同结构，不能套用文本消息格式 |
temperature | number | 否 | 网关前置校验范围为 0–2；具体模型可接受范围可能更窄 |
top_p | number | 否 | 网关前置校验范围为 0–1；是否支持由模型决定 |
max_tokens | integer | 否 | 输出上限；建议使用正整数并遵守模型输出限制 |
stream | boolean | 否 | true 请求 SSE，示例显式使用 false |
tools、tool_choice | array / string / object | 否 | 条件能力，详见 工具调用 |
response_format | object | 否 | 条件能力，详见 结构化输出 |
文档中的基础消息结构适合普通文本；多模态消息和工具调用会使用不同的 messages、content、tool_calls / tool 结构，具体扩展字段是否可用要看所选模型与通道。网关能接收一个字段，不代表所有上游都实现它。通常只调整 temperature 或 top_p 中的一项，避免难以判断采样变化的来源。
完整调用示例
在运行环境中设置 GFW_API_KEY。Python 示例依赖 openai 包，密钥仅从环境变量读取。
curl --fail-with-body --silent --show-error \
--max-time 120 \
https://api.gfw.net/v1/chat/completions \
-H "Authorization: Bearer ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
-H 'Content-Type: application/json' \
--data '{
"model": "deepseek-v4-pro",
"messages": [
{"role": "system", "content": "用简洁的中文回答。"},
{"role": "user", "content": "解释 HTTP 幂等请求的含义。"}
],
"max_tokens": 512,
"stream": false
}'示例关闭 SDK 自动重试，以免排查时重复提交。生产应用应按 错误码与重试 制定有界重试策略。
响应字段
以下为字段结构示意，ID、文本与 Token 数值均为示例：
{
"id": "chatcmpl_example",
"object": "chat.completion",
"model": "deepseek-v4-pro",
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "幂等请求重复执行时具有相同的预期效果。"},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 32, "completion_tokens": 24, "total_tokens": 56}
}| 字段 | 处理建议 |
|---|---|
id | 保存为响应标识；排障还应保存响应头中的请求标识（若提供） |
choices[].message.content | 最终文本；工具调用时可能为空，不应直接当作失败 |
choices[].message.tool_calls | 工具请求，由应用执行并回传，不是网关执行结果 |
choices[].finish_reason | stop 通常表示自然结束；length 表示达到上限；工具模式可能返回 tool_calls |
usage | 接口返回的用量；账单金额以平台用量记录与 元流水为准 |
兼容边界与相关文档
- 文本、图片生成和视频生成使用不同端点，不要把生成图片或视频的模型放进聊天模板。
- 视觉输入需要支持视觉的模型。对话代理的图片校验只允许 Base64 Data URI，不能直接提交外部图片 URL；这不是图片生成接口的通用输入规则。
- 兼容 OpenAI 请求格式不意味着 Files、Batch、音频或其他官方接口已开放。本文不为未核对的端点提供调用承诺。
- 流式返回需要逐事件处理，不能一次性调用 JSON 解析。
继续阅读：Responses API、流式输出、API Key 与鉴权、计费与充值。