聊天补全

聊天补全（Chat Completions）是 TopRouter 最常用的 API 端点，支持多轮对话和流式响应。

API 端点

POST https://toprouter.cc/chat/completions

请求格式

基本参数

参数	类型	必填	说明
model	string	✅	模型 ID，如 anthropic/claude-4.6-sonnet
messages	array	✅	消息数组
temperature	number	❌	采样温度，范围 0-2，默认 1
max_tokens	integer	❌	最大生成 token 数
stream	boolean	❌	是否启用流式响应，默认 false
top_p	number	❌	核采样参数，范围 0-1
stop	string/array	❌	停止生成的标记

消息格式

每条消息包含 role 和 content 两个字段：

Role	说明
system	系统指令，设定 AI 的行为和角色
user	用户输入
assistant	AI 的回复

使用示例

基本请求

from openai import OpenAI

client = OpenAI(
    base_url="https://toprouter.cc",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="anthropic/claude-4.6-sonnet",
    messages=[
        {"role": "system", "content": "你是一个专业的技术顾问。"},
        {"role": "user", "content": "请解释什么是 REST API。"}
    ],
    temperature=0.7,
    max_tokens=1000
)

print(response.choices[0].message.content)

多轮对话

from openai import OpenAI

client = OpenAI(
    base_url="https://toprouter.cc",
    api_key="your-api-key"
)

messages = [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "Python 有哪些主要特点？"},
]

# 第一轮对话
response = client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=messages
)

assistant_message = response.choices[0].message.content
messages.append({"role": "assistant", "content": assistant_message})

# 第二轮对话
messages.append({"role": "user", "content": "请详细说说第一个特点。"})

response = client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=messages
)

print(response.choices[0].message.content)

流式响应

from openai import OpenAI

client = OpenAI(
    base_url="https://toprouter.cc",
    api_key="your-api-key"
)

stream = client.chat.completions.create(
    model="anthropic/claude-4.6-sonnet",
    messages=[
        {"role": "user", "content": "写一篇关于人工智能的短文。"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()  # 换行

TypeScript 示例

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://toprouter.cc',
  apiKey: 'your-api-key',
});

// 普通请求
const response = await client.chat.completions.create({
  model: 'anthropic/claude-4.6-sonnet',
  messages: [
    { role: 'system', content: '你是一个专业的技术顾问。' },
    { role: 'user', content: '请解释什么是 REST API。' },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);

cURL 示例

curl https://toprouter.cc/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "anthropic/claude-4.6-sonnet",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

响应格式

非流式响应

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "anthropic/claude-4.6-sonnet",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "REST API 是一种..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

流式响应（SSE）

流式响应使用 Server-Sent Events (SSE) 格式：

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

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

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

data: [DONE]

参数调优

Temperature

temperature 控制输出的随机性：

值	效果	适用场景
0	确定性输出，几乎无随机性	代码生成、事实问答
0.3-0.7	平衡创造性和准确性	日常对话、文章写作
1.0-2.0	高度随机，更有创造性	创意写作、头脑风暴

Max Tokens

• 用于限制 AI 回复的最大长度
• 不同模型支持的最大 token 数不同
• 建议根据实际需求合理设置，避免浪费

⚠️ 注意

max_tokens 包含输出的 token 数量，不包含输入。如果设置过小，回复可能会被截断。

错误处理

请参考 错误处理 了解常见错误码及处理方式。