# OpenAI 兼容 API

使用 Chat Completions 接口完成对话，了解参数、SDK 地址与协议兼容边界。

## 适用场景 [#适用场景]

Chat Completions 是多轮对话的基本接口。应用提交本轮问题及需要保留的历史消息，读取助手回复，再把回复加入下一轮历史。对话历史由应用维护，不会因为复用 API Key 自动关联。

本文以 GFW 模型 ID `deepseek-v4-pro` 演示。请先在 [模型库](/models) 确认模型仍可用、账号有权访问；模型 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 | 否 | 条件能力，详见 [工具调用](/docs/tool-calls) |
| `response_format` | object | 否 | 条件能力，详见 [结构化输出](/docs/structured-output) |

文档中的基础消息结构适合普通文本；多模态消息和工具调用会使用不同的 `messages`、`content`、`tool_calls` / `tool` 结构，具体扩展字段是否可用要看所选模型与通道。网关能接收一个字段，不代表所有上游都实现它。通常只调整 `temperature` 或 `top_p` 中的一项，避免难以判断采样变化的来源。

## 完整调用示例 [#完整调用示例]

在运行环境中设置 `GFW_API_KEY`。Python 示例依赖 `openai` 包，密钥仅从环境变量读取。



**cURL**


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



**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.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "用简洁的中文回答。"},
        {"role": "user", "content": "解释 HTTP 幂等请求的含义。"},
    ],
    max_tokens=512,
    stream=False,
)

if not response.choices:
    raise RuntimeError("响应未包含 choices")
choice = response.choices[0]
print(choice.message.content or "")
print("finish_reason:", choice.finish_reason)
print("usage:", response.usage)
```




示例关闭 SDK 自动重试，以免排查时重复提交。生产应用应按 [错误码与重试](/docs/errors) 制定有界重试策略。

## 响应字段 [#响应字段]

以下为字段结构示意，ID、文本与 Token 数值均为示例：

```json
{
  "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](/docs/responses)、[流式输出](/docs/streaming)、[API Key 与鉴权](/docs/authentication)、[计费与充值](/docs/billing)。