对话补全 API

对话补全 API

POST /v1/chat/completions 是核心调用端点，完全兼容 OpenAI Chat Completions API，可直接使用 OpenAI 官方 SDK。

认证

Header	值
Authorization	Bearer <api-key>
Content-Type	application/json

API Key 获取与鉴权流程见 认证与调用。

请求参数

参数	类型	必填	说明
model	string	是	模型 ID，如 gpt-4o，可用模型见 模型与定价
messages	array	是	消息数组，每项含 role（system/user/assistant/tool）与 content
max_tokens	integer	否	最大生成 token 数
temperature	number	否	采样温度
stop	array	否	停止序列
frequency_penalty	number	否	频率惩罚
presence_penalty	number	否	存在惩罚
response_format	object	否	JSON 模式，{"type":"json_object"}
seed	integer	否	随机种子
tools	array	否	Function Calling 工具定义
tool_choice	string	否	工具选择（auto / none / 工具名）
stream	boolean	否	是否流式，默认 false

字段限制

• 不支持的字段：top_p、n、logit_bias、user（实体类未定义，传入会被忽略）
• 多模态限制：messages[].content 为 String 类型，不支持 image_url 数组形式的多模态输入。多模态请使用 Anthropic 消息端点。
• tool_choice：仅支持字符串形式（auto / none / 工具名），不支持 {type:"function",function:{name}} 对象形式。

响应

200 OK

{
  "id": "chatcmpl-xxx",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15 }
}

流式响应（stream: true）以 SSE 返回，每个片段为 data: <chunk>\n\n，以 data: [DONE] 结束。

HTTP 状态码

状态码	说明	响应格式
200	成功	OpenAI 格式
400	请求错误（协议校验失败）	OpenAI 错误格式
401	API Key 无效	{"code":"UNAUTHORIZED","message":...}
403	权限不足（应用未授权该渠道）或 IP 黑名单	{"code":"ACCESS_DENIED","message":...}
429	限流	{"error":{"code":"RATE_LIMIT_EXCEEDED","message":...}}
500	服务器错误	ApiResponse 格式（INTERNAL_ERROR）
502	上游 Provider 错误	ApiResponse 格式（code 为错误类型名，如 UPSTREAM_ERROR、MODEL_NOT_FOUND）
503	熔断开启	ApiResponse 格式（code 为 UPSTREAM_ERROR）

错误格式详见 错误码与重试。

场景示例

基础对话

cURL

curl https://{gateway-host}/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}]}'

Python

from openai import OpenAI

client = OpenAI(base_url="https://{gateway-host}/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://{gateway-host}/v1', apiKey: 'sk-xxx' });
const resp = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(resp.choices[0].message.content);

流式响应

cURL

curl https://{gateway-host}/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"讲个故事"}],"stream":true}'

Python

from openai import OpenAI

client = OpenAI(base_url="https://{gateway-host}/v1", api_key="sk-xxx")
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "讲个故事"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://{gateway-host}/v1', apiKey: 'sk-xxx' });
const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '讲个故事' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Function Calling

cURL

curl https://{gateway-host}/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-4o",
    "messages":[{"role":"user","content":"北京天气如何？"}],
    "tools":[{"type":"function","function":{"name":"get_weather","description":"获取天气","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}}],
    "tool_choice":"auto"
  }'

Python

from openai import OpenAI

client = OpenAI(base_url="https://{gateway-host}/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "北京天气如何？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气",
            "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]},
        },
    }],
    tool_choice="auto",
)
print(resp.choices[0].message.tool_calls)

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://{gateway-host}/v1', apiKey: 'sk-xxx' });
const resp = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '北京天气如何？' }],
  tools: [{ type: 'function', function: { name: 'get_weather', description: '获取天气', parameters: { type: 'object', properties: { location: { type: 'string' } }, required: ['location'] } } }],
  tool_choice: 'auto',
});
console.log(resp.choices[0].message.tool_calls);

下一步

• Anthropic 风格调用：Anthropic 消息 API
• 协议互转：协议转换
• 更多示例：调用示例