文本

创建聊天补全

根据消息生成聊天回答

POST
/v1/chat/completions

请求体

可选参数的支持情况、取值和默认值取决于所选模型。设置采样、推理或工具选项前,请查看其模型详情。模型无法满足的控制项(例如部分模型上大于 1 的 n)会以 4xx 错误拒绝;seed、惩罚项这类次要采样控制项则可能被忽略。

modelstring必填

要使用的模型 ID。可用选项见 Models。

messagesarray必填

组成对话的消息列表。

每个消息对象包含:

  • role (字符串): system, developer, user, assistant, tool, function
  • content (string | array | null): 消息内容

包含 tool_calls 的 assistant 消息可以省略 content,或将其设为 null。

当 content 是数组时,TokenLab 为兼容模型支持结构化多模态块:

  • text: { "type": "text", "text": "..." }
  • 图片: { "type": "image_url", "image_url": { "url": "https://..." } }
  • 视频: { "type": "video_url", "video_url": { "url": "https://..." } }
  • 音频: { "type": "input_audio", "input_audio": { "data": "https://... 或 base64 data URL", "format": "wav" } },或 { "type": "audio_url", "audio_url": { "url": "https://..." } }

多模态输入请使用可公开访问的 https URL。图片也可以用 base64 data URL 发送。支持的媒体类型取决于所选模型。

temperaturenumber

采样温度。是否支持、允许的取值和默认值取决于所选模型;省略此字段即可使用模型默认值。

max_tokensinteger

要生成的最大 token 数。max_tokens 和 max_completion_tokens 只发送其一,不要同时发送:经其他协议服务的模型可能拒绝同时带有两者的请求。

对会思考的模型,思考 token 计入此上限。上限过小时,全部额度可能都用在思考上,导致消息正文为空,已用 token 仍会计费。请调大上限,或在模型允许时关闭思考,例如 "reasoning_effort": "none"。在 deepseek-v4.1-flash(别名 deepseek-flash)上,"thinking": {"type": "disabled"} 同样可以关闭思考。

请求运行前,TokenLab 会检查余额能否覆盖这个最大值。余额较低时,过大的值即使实际回答很短也可能返回 402。

streamboolean默认值: false

设为 true 时,通过服务器发送事件(SSE)返回消息增量。见流式响应。

对于长输出(数千 token 及以上),请设置 stream: true,以免客户端和代理在等待完整响应时超时。

stream_optionsobject

流式响应设置。include_usage: true 会在 data: [DONE] 之前多返回一个带 token 用量的数据块。不设置时,流中不含用量。

top_pnumber

Nucleus 采样参数。建议更改此参数或 temperature,而不是同时更改两者。

frequency_penaltynumber

值在 -2.0 到 2.0 之间。正值会惩罚重复出现的 token。

presence_penaltynumber

值在 -2.0 到 2.0 之间。正值会惩罚已出现在文本中的 token。

stopstring | array

停止序列或序列列表。是否支持及序列数量限制取决于所选模型。

toolsarray

模型可能调用的工具列表(函数调用)。每个工具的形式为 { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }。见结构化输出与工具调用。

tool_choicestring | object

控制模型如何使用工具。选项:auto、none、required,或用 { "type": "function", "function": { "name": "..." } } 强制调用某个工具。

parallel_tool_callsboolean

在所选模型支持时,允许助手在同一轮中发出多个工具调用。

max_completion_tokensinteger

补全的上限,包含思考 token。是 max_tokens 的替代写法,新的 OpenAI 模型系列使用。两者只发送其一。

reasoning_effortstring

支持推理的模型使用的推理强度,允许的取值取决于所选模型。

对 Claude 模型,该值设置模型的思考:支持自适应思考的模型使用对应的 effort 档位,使用思考预算的模型使用对应的预算。在允许关闭思考的模型上,none 会关闭思考。模型不支持的取值会以 400 和错误码 invalid_value 拒绝,错误信息会列出支持的取值。思考开启时,Claude 不接受不等于 1 的 temperature、top_k、超出 0.95–1 的 top_p,也不接受预填充的 assistant 消息。强制的 tool_choice 可以与自适应思考同时使用,但不能与思考预算同时使用。

anthropic_optionsobject

Claude 模型的选项。

  • prompt_caching(boolean):设为 true 时缓存提示词的开头部分。TokenLab 会把系统提示词的末尾和最新一条用户消息标为缓存点。之后开头内容相同的请求会从缓存读取这部分。此选项和你自己写的 cache_control 标记二选一,不要同时使用。
  • prompt_caching_ttl(string):5m(默认)或 1h。如果处理该请求的服务无法保留 1 小时的缓存,TokenLab 可以改用 5 分钟缓存,而不是拒绝请求。

extra.prompt_caching 和 extra.prompt_caching_ttl 是相同的选项。价格和查看缓存 token 的方法见提示缓存。

seedinteger

供支持此功能的模型使用的采样种子,不保证生成完全相同的输出。

ninteger

要生成的补全数量。支持该参数的模型接受 1-128,许多模型只支持 1。

logprobsboolean

是否返回对数概率(log probabilities)。

top_logprobsinteger

要返回的顶级对数概率数量(0-20)。需要 logprobs: true。

top_kinteger

供支持此功能的模型使用的 Top-K 采样参数。

response_formatobject

响应格式。可用 {"type": "text"}(默认)、JSON 模式 {"type": "json_object"},或 JSON Schema {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}。支持情况取决于所选模型。见结构化输出与工具调用。

logit_biasobject

修改指定 token 出现的可能性。将 token ID(以字符串形式)映射到 -100 到 100 的偏差值。是否支持取决于所选模型。

service_tierstring

TokenLab 以标准服务档位处理并计费 Chat 请求。接受 auto 和 default。其他取值(如 flex、priority)会从请求中移除,请求按标准价格计费。

userstring

终端用户标识,可用于安全与滥用防护。

响应

idstring

补全的唯一标识符。

objectstring

始终为 chat.completion。

createdinteger

补全创建时的 Unix 时间戳。

modelstring

用于补全的模型。

choicesarray

补全选项列表。

每个选项包含:

  • index (integer): 选项的索引
  • message (object): 生成的消息
  • finish_reason (string): 模型停止的原因,例如 stop、length、tool_calls 或 content_filter

模型进行思考时,message 还可能包含:

  • reasoning_content (string): 思考文本。有些模型只返回摘要,或不返回文本。
  • reasoning_details (array): 带签名的思考块。要在思考的基础上继续对话(例如工具调用之后),请在 assistant 消息里原样传回。

流式响应中,这些字段以 delta.reasoning_content 和 delta.reasoning_details 返回。

usageobject

token 使用统计。

  • prompt_tokens (integer): 提示中的 token 数
  • completion_tokens (integer): 补全中的 token 数,包含思考 token
  • total_tokens (integer): 使用的总 token 数
  • prompt_tokens_details.cached_tokens (integer): 从缓存读取的提示 token 数
  • cache_creation_input_tokens (integer): 写入缓存的提示 token 数。仅在大于 0 时出现
  • completion_tokens_details.reasoning_tokens (integer): 思考 token 数(模型返回时提供)

流式响应中,只有 stream_options.include_usage 为 true 时才返回用量。

请求

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

多模态示例

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

响应

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

流式响应

设置 stream: true 后,响应为 text/event-stream。每个事件是 data: {...},内容为 chat.completion.chunk 对象,choices[].delta 携带新增文本、工具调用参数或思考文本。流以 data: [DONE] 结束。以 : 开头的行是保活注释,忽略即可。流在没有 [DONE] 或没有 finish_reason 时结束,说明响应不完整。见流式传输。

错误

错误使用 OpenAI 风格的 error 对象。常见情况:400 表示字段无效或模型不接受该取值,401 表示密钥无效,402 表示余额不足,413 表示输入超出大小限制,429 表示触发速率限制。见处理 API 错误。

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

可选键,用于防止同一请求被重复执行。请为每个请求发送一个新的唯一值(如 UUID),并在超时重试时保持不变。使用相同键的重试不会再次执行:它会返回 409 状态码及 idempotency_replay_unavailable 错误,若请求体发生变化,通常返回 idempotency_conflict。例外情况:当非 streaming 结果在客户端断开连接后完成时,在 24 小时内使用相同键和请求体进行重试,将返回该结果(最大 1 MB),并包含 Idempotent-Replayed: true 响应头,且不会产生二次扣费。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。

长度1 <= length <= 255

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json