聊天(Chat)
对话补全支持三种厂家协议,格式由模型决定:Anthropic 模型使用 Anthropic Messages,Google 模型使用 Gemini 原生格式,其余大语言模型使用 OpenAI 兼容格式。
按模型厂家选择格式
| 格式 | 端点 | 适合 |
|---|---|---|
| OpenAI Chat Completions | POST /v1/chat/completions | 除 Anthropic、Google 外的其他大语言模型 |
| Anthropic Messages | POST /v1/messages | Anthropic 厂家的 Claude 系列模型 |
| Gemini generateContent | POST /v1beta/models/{model}:generateContent | Google 厂家的 Gemini 系列模型 |
三种格式共用同一把密钥API Key 与计费账户相同,但请求路径、鉴权头和请求体由模型厂家决定,三种格式不能互换。模型 ID 从 GET /v1/models 或模型广场获取。
OpenAI 格式
用于除 Anthropic、Google 外的其他大语言模型。支持流式与非流式,字段与 OpenAI /v1/chat/completions 对齐。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 模型 ID。 |
messages | array<object> | 必填 | 对话消息列表,每条含 role(system / user / assistant / tool)与 content。视觉模型的 content 可为数组,混排 text 与 image_url。 |
temperature | number | 可选 | 采样温度,取值 0 ~ 2,默认 1。 |
top_p | number | 可选 | 核采样,取值 0 ~ 1,默认 1。与 temperature 建议只调其一。 |
n | integer | 可选 | 生成候选数量,默认 1。 |
stream | boolean | 可选 | 是否流式响应,默认 false。 |
stream_options | object | 可选 | 流式附加选项,如 {"include_usage": true} 在最后一个分片带上用量统计。 |
stop | string / array | 可选 | 停止序列,可传字符串或字符串数组。 |
max_tokens | integer | 可选 | 最大生成 Token 数。 |
max_completion_tokens | integer | 可选 | 最大补全 Token 数。当前网关中它与 max_tokens 行为不同;推理 Token 也可能占用该上限并减少可见输出,请按目标模型分别测试。 |
presence_penalty | number | 可选 | 存在惩罚,-2 ~ 2,默认 0。 |
frequency_penalty | number | 可选 | 频率惩罚,-2 ~ 2,默认 0。 |
logit_bias | object | 可选 | 指定 Token 的采样偏置。 |
tools | array<object> | 可选 | 可调用的工具(函数)定义列表。 |
tool_choice | string / object | 可选 | 工具选择模式,取 none / auto / required,或传对象指定具体函数。 |
response_format | object | 可选 | 结构化输出,如 {"type": "json_object"} 或 {"type": "json_schema", ...}。 |
seed | integer | 可选 | 随机种子,用于提升可复现性(不保证完全一致)。 |
reasoning_effort | string | 可选 | 推理强度,取 low / medium / high,仅支持推理的模型有效。 |
user | string | 可选 | 终端用户标识,便于滥用排查。 |
参数取决于模型不同模型支持的参数集不同。传入模型不支持的参数时,网关会忽略该参数或返回 400。模型能力(视觉、工具调用、JSON 模式、流式)可在模型广场查看能力标签。
调用示例
curl -X POST https://api.tokgate.io/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-***" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{"role": "system", "content": "你是一个严谨的技术助手"},
{"role": "user", "content": "解释一下什么是核采样"}
],
"temperature": 0.7,
"max_tokens": 1024
}'
from openai import OpenAI
client = OpenAI(
api_key="sk-***",
base_url="https://api.tokgate.io/v1",
)
resp = client.chat.completions.create(
model="deepseek-v4-pro",
messages=[
{"role": "system", "content": "你是一个严谨的技术助手"},
{"role": "user", "content": "解释一下什么是核采样"},
],
temperature=0.7,
max_tokens=1024,
)
print(resp.choices[0].message.content)
print(resp.usage)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.TOKGATE_API_KEY,
baseURL: "https://api.tokgate.io/v1",
});
const resp = await client.chat.completions.create({
model: "deepseek-v4-pro",
messages: [
{ role: "system", content: "你是一个严谨的技术助手" },
{ role: "user", content: "解释一下什么是核采样" },
],
temperature: 0.7,
max_tokens: 1024,
});
console.log(resp.choices[0].message.content);
响应结构
{
"id": "chatcmpl-xxxxxxxx",
"object": "chat.completion",
"created": 1779348818,
"model": "deepseek-v4-pro",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "核采样(top-p)是……",
"reasoning_content": null,
"tool_calls": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 186,
"total_tokens": 228,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 }
},
"system_fingerprint": null
}
| 字段 | 说明 |
|---|---|
choices[].finish_reason | 结束原因:stop(自然结束)/ length(达到长度上限)/ tool_calls(请求调用工具)/ content_filter(内容拦截)。 |
choices[].message.tool_calls | 模型请求调用的工具列表,含 id、function.name、function.arguments(JSON 字符串)。 |
choices[].message.reasoning_content | 推理型模型返回的思考过程,普通模型为 null。 |
usage | 本次调用的 Token 用量,用于对账。缓存命中量在 prompt_tokens_details.cached_tokens。 |
流式输出
设置 stream: true,服务端以 Server-Sent Events 逐块返回,最后以 data: [DONE] 结束。适合打字机效果的对话界面。
stream = client.chat.completions.create(
model="deepseek-v4-pro",
messages=[{"role": "user", "content": "讲一个关于出海的短故事"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)
const stream = await client.chat.completions.create({
model: "deepseek-v4-pro",
messages: [{ role: "user", content: "讲一个关于出海的短故事" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
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]
工具调用
在 tools 里声明函数,模型在需要时返回 tool_calls;你执行函数后,把结果以 role: "tool" 追加进 messages 再次请求,模型据此生成最终回答。
{
"model": "deepseek-v4-pro",
"messages": [{"role": "user", "content": "深圳现在天气怎么样?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的实时天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名,如 深圳"}
},
"required": ["city"]
}
}
}
],
"tool_choice": "auto"
}
Anthropic 格式
仅用于 Anthropic 厂家的 Claude 系列模型。Anthropic Messages 与 OpenAI 格式的主要差异:system 是顶层字段而非一条消息;max_tokens 必填;响应内容是 content 块数组;用量字段叫 input_tokens / output_tokens。
请求头
| Header | 必填 | 说明 |
|---|---|---|
x-api-key | 必填 | 你的 API Key。也可改用 Authorization: Bearer <key>。 |
anthropic-version | 必填 | 协议版本,固定 2023-06-01。官方 SDK 会自动带上。 |
Content-Type | 必填 | application/json |
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 模型 ID。 |
messages | array<object> | 必填 | 对话消息,role 只能是 user 或 assistant,需交替出现。content 可为字符串或内容块数组(text / image / tool_use / tool_result)。 |
max_tokens | integer | 必填 | 最大生成 Token 数。Anthropic 格式下此字段必填。 |
system | string / array | 可选 | 系统提示词,顶层字段。不要放进 messages。 |
temperature | number | 可选 | 采样温度,取值 0 ~ 1。 |
top_p | number | 可选 | 核采样,取值 0 ~ 1。 |
top_k | integer | 可选 | 只从概率最高的 K 个 Token 中采样。 |
stream | boolean | 可选 | 是否流式响应,默认 false。 |
stop_sequences | array<string> | 可选 | 自定义停止序列。命中时 stop_reason 为 stop_sequence。 |
tools | array<object> | 可选 | 工具定义,字段为 name / description / input_schema。 |
tool_choice | object | 可选 | 如 {"type": "auto"}、{"type": "any"}、{"type": "tool", "name": "..."}。 |
thinking | object | 可选 | 扩展思考,如 {"type": "enabled", "budget_tokens": 4096},仅支持该能力的模型有效。 |
metadata | object | 可选 | 附加信息,如 {"user_id": "..."}。 |
调用示例
curl -X POST https://api.tokgate.io/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: sk-***" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "你是一个严谨的技术助手",
"messages": [
{"role": "user", "content": "解释一下什么是核采样"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-***",
base_url="https://api.tokgate.io",
)
msg = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="你是一个严谨的技术助手",
messages=[{"role": "user", "content": "解释一下什么是核采样"}],
)
print(msg.content[0].text)
print(msg.usage)
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.TOKGATE_API_KEY,
baseURL: "https://api.tokgate.io",
});
const msg = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
system: "你是一个严谨的技术助手",
messages: [{ role: "user", content: "解释一下什么是核采样" }],
});
console.log(msg.content[0].text);
base_url 不带 /v1Anthropic SDK 会自己拼上 /v1/messages,所以 base_url 填 https://api.tokgate.io。而 OpenAI SDK 需要填到 https://api.tokgate.io/v1。
响应结构
{
"id": "msg_xxxxxxxx",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{ "type": "text", "text": "核采样(top-p)是……" }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 38,
"output_tokens": 174,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
| 字段 | 说明 |
|---|---|
content[] | 内容块数组。type 为 text(文本)、thinking(思考过程)或 tool_use(请求调用工具,含 id / name / input)。 |
stop_reason | end_turn(自然结束)/ max_tokens(达到上限)/ stop_sequence(命中停止序列)/ tool_use(等待工具结果)。 |
usage.input_tokens / output_tokens | 输入与输出 Token 数,对应 OpenAI 格式的 prompt_tokens / completion_tokens。 |
流式事件
设置 stream: true,服务端返回带 event: 名称的 SSE 事件流。与 OpenAI 的单一 chunk 不同,需要按事件类型分别处理。
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","role":"assistant","content":[],"usage":{"input_tokens":38,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"核采样"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":174}}
event: message_stop
data: {"type":"message_stop"}
| 事件 | 含义 |
|---|---|
message_start | 消息开始,带初始元信息与输入 Token 数。 |
content_block_start / content_block_delta / content_block_stop | 某个内容块的开始 / 增量 / 结束。文本增量在 delta.text。 |
message_delta | 消息级增量,带最终 stop_reason 与输出 Token 数。 |
message_stop | 流结束。 |
ping | 心跳,可忽略。 |
与 OpenAI 格式的字段对照
| 用途 | OpenAI 格式 | Anthropic 格式 |
|---|---|---|
| 系统提示 | messages[0] 的 role: "system" | 顶层 system |
| 最大输出 | max_tokens(可选) | max_tokens(必填) |
| 停止序列 | stop | stop_sequences |
| 回答文本 | choices[0].message.content | content[0].text |
| 结束原因 | finish_reason(stop) | stop_reason(end_turn) |
| 输入用量 | usage.prompt_tokens | usage.input_tokens |
| 输出用量 | usage.completion_tokens | usage.output_tokens |
| 工具定义参数 | function.parameters | input_schema |
| 工具调用结果回填 | role: "tool" 消息 | role: "user" 消息里的 tool_result 块 |
Gemini 原生格式
仅用于 Google Gemini 模型。模型 ID 放在 URL 路径中,请求体使用 Gemini 原生的 contents / parts 结构,不使用 OpenAI 的 messages。
请求头
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 必填 | 使用 Bearer sk-***。 |
Content-Type | 必填 | application/json |
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
contents | array<object> | 必填 | 对话内容列表,每项包含 role 与 parts;文本放在 parts[].text。 |
systemInstruction | object | 可选 | 系统指令,使用 parts 内容结构。 |
generationConfig | object | 可选 | 生成配置,如 temperature、topP、maxOutputTokens。 |
tools | array<object> | 可选 | Gemini 原生工具声明,如 functionDeclarations。 |
调用示例
curl -X POST "https://api.tokgate.io/v1beta/models/你的Gemini模型ID:generateContent" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-***" \
-d '{
"systemInstruction": {
"parts": [{"text": "你是一个严谨的技术助手"}]
},
"contents": [{
"role": "user",
"parts": [{"text": "解释一下什么是核采样"}]
}],
"generationConfig": {
"temperature": 0.7,
"maxOutputTokens": 1024
}
}'
响应结构
回答文本位于 candidates[0].content.parts[].text;结束原因位于 finishReason;Token 用量位于 usageMetadata。
流式输出
流式调用使用 streamGenerateContent,请求体与非流式接口相同;添加 alt=sse 后按 Server-Sent Events 逐块接收 Gemini 原生响应。
错误处理
状态码语义与错误体结构见 API 文档 · 错误码。聊天接口的高频问题:
400+messages相关报错:Anthropic 格式要求user/assistant交替,且不接受role: "system"的消息。400+ 缺少max_tokens:Anthropic 格式该字段必填。404 model_not_found:模型 ID 写错,或该模型不在密钥白名单允许范围内(后者通常是403)。- 流式请求中断:检查是否有中间层(Nginx、CDN、企业代理)开启了响应缓冲,需要关闭缓冲才能实时透传 SSE。
