文档目录

文本与对话

chat/completions 字段、流式帧、工具调用,以及 Anthropic 与 Gemini 两套原生协议的端点。

内容最后核对:2026-11-18

本页目录

POST /v1/chat/completions

字段类型说明
modelstring必填,显示名或规范 id
messagesarray必填,OpenAI 消息数组
streambooleantrue 时返回 SSE
max_tokensinteger也认 max_completion_tokens
temperature / top_pnumber
frequency_penalty / presence_penaltynumber
seedinteger部分上游不支持,会被忽略
stopstring / array
tools / tool_choice / parallel_tool_calls跨协议时转换后透传

非流式响应是标准 OpenAI 形状:

{"id": "chatcmpl-...", "object": "chat.completion", "created": 1763000000,
 "model": "<显示名>",
 "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好"},
              "finish_reason": "stop"}],
 "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}}

usage 是计费依据:上游给了就用上游的,没给就按本地分词估算,估算时响应里不会伪装成精确值。

流式

请求里写 stream: true,或者直接打 /v1/chat/completions/stream:

data: {"choices":[{"delta":{"content":"你"}}]}

data: {"choices":[{"delta":{"content":"好"},"finish_reason":"stop"}]}

data: [DONE]
  • 路径 /stream 已经表达意图,请求体里的 stream 会被忽略 —— 不需要同时改两个开关。
  • [DONE] 是网关自己发的,表示流正常结束。没收到它而连接断了,就是中途断开。
  • 思考过程在 delta.reasoning_content,与正文分开;不想用直接忽略。
  • 延迟统计是首帧到达,不是整段输出时长。

读法与实践细节见流式输出。

工具调用

tools 会在跨协议时被翻译成上游的形状(例如 Anthropic 的 input_schema)。目标模型必须支持工具调用;不支持时上游会忽略 tools,表现为模型直接回答而没调函数 —— 不会报错,因为从上游视角看这请求完全合法。

POST /v1/messages(Anthropic 协议)

Anthropic 入站协议,字段与 Anthropic 一致(system、max_tokens、content 块数组、tool_use)。

  • 密钥可用 x-api-key,也可用 Authorization: Bearer。
  • 错误信封带顶层 {"type":"error"},与本网关其它 /v1 端点不同 —— 这是 Anthropic 协议本身的要求。
  • 流式事件是 Anthropic 的 message_start / content_block_delta / message_stop,不是 OpenAI 的 data:。

POST /v1/messages/count_tokens

按 Anthropic 形状数 token。不产生费用、不写使用日志 —— 它是估算接口,不是一次调用。

Gemini 原生协议

端点说明
POST /v1beta/models/{model}:generateContent一次性生成
POST /v1beta/models/{model}:streamGenerateContent流式(alt=sse)
POST /v1beta/models/{model}:countTokens数 token

密钥可用 x-goog-api-key 或 ?key=。请求体是 Gemini 的 contents / generationConfig 形状,不是 OpenAI 的 messages。

/v1beta 与 /v1 同属模型调用命名空间:错误信封仍是 OpenAI 嵌套形状(不是 Gemini 的 {"error":{"code":429,...}} 数值形状),因为错误由本站生成。

常见参数差异

你想做的事OpenAI 写法注意
限制输出长度max_tokens也认 max_completion_tokens;Anthropic 协议里叫 max_tokens 且必填
结构化输出response_format不是所有上游都支持;不支持时会被忽略而不是报错
温度temperature部分推理模型只接受默认值
多模态输入content 数组里的 image_url目标模型必须能读图,否则 400 model.modality_not_supported