OpenAI 聊天补全

通过 OpenAI 兼容接口调用 GPT 系列模型。

请求

POST https://api.clawdrouter.com/v1/chat/completions

请求头

名称	必填	类型	说明
Authorization	是	string	Bearer YOUR_API_KEY
Content-Type	是	string	application/json
Request-Id	否	string	客户系统生成的唯一业务标识

请求体

参数	类型	必填	默认值	说明
model	string	是	—	模型标识，参考模型列表
messages	array	是	—	对话消息列表，详见下方 Messages 格式
stream	boolean	否	false	是否启用流式输出。启用后，Token 将通过 SSE 逐步返回，以 data: [DONE] 结束
temperature	number	否	1	采样温度，取值 0~2。值越高输出越随机，值越低越集中确定。建议不要同时修改 top_p
top_p	number	否	1	核采样参数，取值 0~1。0.1 表示只考虑概率质量前 10% 的 Token。建议不要同时修改 temperature
max_tokens	integer	否	4096	生成的最大 Token 数
stop	string / array	否	—	最多 4 个停止序列，模型生成到这些序列时会停止
presence_penalty	number	否	0	存在惩罚，取值 -2.0~2.0。正值会惩罚已出现的 Token，鼓励模型讨论新话题
frequency_penalty	number	否	0	频率惩罚，取值 -2.0~2.0。正值会根据 Token 出现频率进行惩罚，降低逐字重复的可能性
n	integer	否	1	为每条输入消息生成多少个补全选项
seed	integer	否	—	用于确定性采样。相同 seed 和参数的请求将尽量返回相同结果
logprobs	boolean	否	false	是否返回输出 Token 的对数概率
top_logprobs	integer	否	—	取值 0~5，指定每个位置返回的最可能 Token 数。需要 logprobs: true
response_format	object	否	—	指定输出格式，用于启用 JSON 模式
tools	array	否	—	模型可调用的工具列表 (Function Calling)
tool_choice	string / object	否	—	控制模型调用工具的行为：none / auto / 指定函数
user	string	否	—	终端用户的唯一标识符
logit_bias	object	否	—	修改指定 Token 出现的可能性，值从 -100 到 100

Messages 格式

[
  {"role": "system", "content": "你是一个有用的助手"},
  {"role": "user", "content": "你好"},
  {"role": "assistant", "content": "你好！有什么可以帮助你的？"},
  {"role": "user", "content": "介绍一下量子计算"}
]

支持的 role 类型：

Role	说明
system	系统提示词，设定模型的行为和角色
user	用户输入的消息
assistant	模型的回复（用于多轮对话）
tool	工具调用的返回结果

Tool Choice

tool_choice 参数控制模型如何使用工具：

• "none" — 模型不调用任何工具，只生成文本
• "auto" — 模型自行决定是否调用工具（有工具时的默认值）
• {"type": "function", "function": {"name": "my_function"}} — 强制模型调用指定函数

请求示例

基础请求

curl https://api.clawdrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你是谁？"}
    ],
    "stream": false
  }'

流式请求

curl https://api.clawdrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "写一首关于春天的诗"}
    ],
    "stream": true
  }'

响应

非流式响应

{
  "id": "chatcmpl-B7zPsoqemovClguYiYNxWn7LkL1uT",
  "object": "chat.completion",
  "created": 1741244080,
  "model": "gpt-4o-2024-11-20",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个人工智能助手，旨在为你提供信息、回答问题、以及协助解决问题。你有什么问题吗？",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 63,
    "total_tokens": 73,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_a42ed5ff0c",
  "traceId": "AOAI20250306B3DE5A14473A46AD8AEEBD2C248AE841"
}

响应字段说明

字段	类型	说明
id	string	本次补全的唯一标识
object	string	固定为 chat.completion
created	integer	创建时间的 Unix 时间戳
model	string	实际使用的模型版本
choices	array	补全结果列表
choices[].message	object	模型生成的消息
choices[].finish_reason	string	停止原因：stop（正常结束）/ length（达到长度限制）/ tool_calls（调用工具）
usage	object	Token 用量统计
traceId	string	系统生成的 traceId，用于问题追踪

流式响应

流式模式下，响应以 SSE (Server-Sent Events) 格式返回：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]