新用户注册即赠体验积分 立即领取 →
AI 模型接口

聊天(Chat)

对话补全支持三种厂家协议,格式由模型决定:Anthropic 模型使用 Anthropic Messages,Google 模型使用 Gemini 原生格式,其余大语言模型使用 OpenAI 兼容格式

按模型厂家选择格式

格式端点适合
OpenAI Chat CompletionsPOST /v1/chat/completions除 Anthropic、Google 外的其他大语言模型
Anthropic MessagesPOST /v1/messagesAnthropic 厂家的 Claude 系列模型
Gemini generateContentPOST /v1beta/models/{model}:generateContentGoogle 厂家的 Gemini 系列模型

三种格式共用同一把密钥API Key 与计费账户相同,但请求路径、鉴权头和请求体由模型厂家决定,三种格式不能互换。模型 ID 从 GET /v1/models 或模型广场获取。

OpenAI 格式

POST https://api.tokgate.io/v1/chat/completions

用于除 Anthropic、Google 外的其他大语言模型。支持流式与非流式,字段与 OpenAI /v1/chat/completions 对齐。

请求参数

参数类型必填说明
modelstring必填模型 ID。
messagesarray<object>必填对话消息列表,每条含 rolesystem / user / assistant / tool)与 content。视觉模型的 content 可为数组,混排 textimage_url
temperaturenumber可选采样温度,取值 0 ~ 2,默认 1。
top_pnumber可选核采样,取值 0 ~ 1,默认 1。与 temperature 建议只调其一。
ninteger可选生成候选数量,默认 1。
streamboolean可选是否流式响应,默认 false
stream_optionsobject可选流式附加选项,如 {"include_usage": true} 在最后一个分片带上用量统计。
stopstring / array可选停止序列,可传字符串或字符串数组。
max_tokensinteger可选最大生成 Token 数。
max_completion_tokensinteger可选最大补全 Token 数。当前网关中它与 max_tokens 行为不同;推理 Token 也可能占用该上限并减少可见输出,请按目标模型分别测试。
presence_penaltynumber可选存在惩罚,-2 ~ 2,默认 0。
frequency_penaltynumber可选频率惩罚,-2 ~ 2,默认 0。
logit_biasobject可选指定 Token 的采样偏置。
toolsarray<object>可选可调用的工具(函数)定义列表。
tool_choicestring / object可选工具选择模式,取 none / auto / required,或传对象指定具体函数。
response_formatobject可选结构化输出,如 {"type": "json_object"}{"type": "json_schema", ...}
seedinteger可选随机种子,用于提升可复现性(不保证完全一致)。
reasoning_effortstring可选推理强度,取 low / medium / high,仅支持推理的模型有效。
userstring可选终端用户标识,便于滥用排查。

参数取决于模型不同模型支持的参数集不同。传入模型不支持的参数时,网关会忽略该参数或返回 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模型请求调用的工具列表,含 idfunction.namefunction.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 格式

POST https://api.tokgate.io/v1/messages

仅用于 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

请求参数

参数类型必填说明
modelstring必填模型 ID。
messagesarray<object>必填对话消息,role 只能是 userassistant,需交替出现。content 可为字符串或内容块数组(text / image / tool_use / tool_result)。
max_tokensinteger必填最大生成 Token 数。Anthropic 格式下此字段必填
systemstring / array可选系统提示词,顶层字段。不要放进 messages
temperaturenumber可选采样温度,取值 0 ~ 1。
top_pnumber可选核采样,取值 0 ~ 1。
top_kinteger可选只从概率最高的 K 个 Token 中采样。
streamboolean可选是否流式响应,默认 false
stop_sequencesarray<string>可选自定义停止序列。命中时 stop_reasonstop_sequence
toolsarray<object>可选工具定义,字段为 name / description / input_schema
tool_choiceobject可选{"type": "auto"}{"type": "any"}{"type": "tool", "name": "..."}
thinkingobject可选扩展思考,如 {"type": "enabled", "budget_tokens": 4096},仅支持该能力的模型有效。
metadataobject可选附加信息,如 {"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_urlhttps://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[]内容块数组。typetext(文本)、thinking(思考过程)或 tool_use(请求调用工具,含 id / name / input)。
stop_reasonend_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必填
停止序列stopstop_sequences
回答文本choices[0].message.contentcontent[0].text
结束原因finish_reasonstopstop_reasonend_turn
输入用量usage.prompt_tokensusage.input_tokens
输出用量usage.completion_tokensusage.output_tokens
工具定义参数function.parametersinput_schema
工具调用结果回填role: "tool" 消息role: "user" 消息里的 tool_result

Gemini 原生格式

POST https://api.tokgate.io/v1beta/models/{model}:generateContent

仅用于 Google Gemini 模型。模型 ID 放在 URL 路径中,请求体使用 Gemini 原生的 contents / parts 结构,不使用 OpenAI 的 messages

请求头

Header必填说明
Authorization必填使用 Bearer sk-***
Content-Type必填application/json

请求参数

参数类型必填说明
contentsarray<object>必填对话内容列表,每项包含 roleparts;文本放在 parts[].text
systemInstructionobject可选系统指令,使用 parts 内容结构。
generationConfigobject可选生成配置,如 temperaturetopPmaxOutputTokens
toolsarray<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

流式输出

POST https://api.tokgate.io/v1beta/models/{model}:streamGenerateContent?alt=sse

流式调用使用 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。