文本
创建聊天补全
根据消息生成聊天回答
请求体
可选参数的支持情况、取值和默认值取决于所选模型。设置采样、推理或工具选项前,请查看其模型详情。模型无法满足的控制项(例如部分模型上大于 1 的 n)会以 4xx 错误拒绝;seed、惩罚项这类次要采样控制项则可能被忽略。
要使用的模型 ID。可用选项见 Models。
组成对话的消息列表。
每个消息对象包含:
role(字符串):system,developer,user,assistant,tool,functioncontent(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 发送。支持的媒体类型取决于所选模型。
采样温度。是否支持、允许的取值和默认值取决于所选模型;省略此字段即可使用模型默认值。
要生成的最大 token 数。max_tokens 和 max_completion_tokens 只发送其一,不要同时发送:经其他协议服务的模型可能拒绝同时带有两者的请求。
对会思考的模型,思考 token 计入此上限。上限过小时,全部额度可能都用在思考上,导致消息正文为空,已用 token 仍会计费。请调大上限,或在模型允许时关闭思考,例如 "reasoning_effort": "none"。在 deepseek-v4.1-flash(别名 deepseek-flash)上,"thinking": {"type": "disabled"} 同样可以关闭思考。
请求运行前,TokenLab 会检查余额能否覆盖这个最大值。余额较低时,过大的值即使实际回答很短也可能返回 402。
false设为 true 时,通过服务器发送事件(SSE)返回消息增量。见流式响应。
对于长输出(数千 token 及以上),请设置 stream: true,以免客户端和代理在等待完整响应时超时。
流式响应设置。include_usage: true 会在 data: [DONE] 之前多返回一个带 token 用量的数据块。不设置时,流中不含用量。
Nucleus 采样参数。建议更改此参数或 temperature,而不是同时更改两者。
值在 -2.0 到 2.0 之间。正值会惩罚重复出现的 token。
值在 -2.0 到 2.0 之间。正值会惩罚已出现在文本中的 token。
停止序列或序列列表。是否支持及序列数量限制取决于所选模型。
模型可能调用的工具列表(函数调用)。每个工具的形式为 { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }。见结构化输出与工具调用。
控制模型如何使用工具。选项:auto、none、required,或用 { "type": "function", "function": { "name": "..." } } 强制调用某个工具。
在所选模型支持时,允许助手在同一轮中发出多个工具调用。
补全的上限,包含思考 token。是 max_tokens 的替代写法,新的 OpenAI 模型系列使用。两者只发送其一。
支持推理的模型使用的推理强度,允许的取值取决于所选模型。
对 Claude 模型,该值设置模型的思考:支持自适应思考的模型使用对应的 effort 档位,使用思考预算的模型使用对应的预算。在允许关闭思考的模型上,none 会关闭思考。模型不支持的取值会以 400 和错误码 invalid_value 拒绝,错误信息会列出支持的取值。思考开启时,Claude 不接受不等于 1 的 temperature、top_k、超出 0.95–1 的 top_p,也不接受预填充的 assistant 消息。强制的 tool_choice 可以与自适应思考同时使用,但不能与思考预算同时使用。
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 的方法见提示缓存。
供支持此功能的模型使用的采样种子,不保证生成完全相同的输出。
要生成的补全数量。支持该参数的模型接受 1-128,许多模型只支持 1。
是否返回对数概率(log probabilities)。
要返回的顶级对数概率数量(0-20)。需要 logprobs: true。
供支持此功能的模型使用的 Top-K 采样参数。
响应格式。可用 {"type": "text"}(默认)、JSON 模式 {"type": "json_object"},或 JSON Schema {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}。支持情况取决于所选模型。见结构化输出与工具调用。
修改指定 token 出现的可能性。将 token ID(以字符串形式)映射到 -100 到 100 的偏差值。是否支持取决于所选模型。
TokenLab 以标准服务档位处理并计费 Chat 请求。接受 auto 和 default。其他取值(如 flex、priority)会从请求中移除,请求按标准价格计费。
终端用户标识,可用于安全与滥用防护。
响应
补全的唯一标识符。
始终为 chat.completion。
补全创建时的 Unix 时间戳。
用于补全的模型。
补全选项列表。
每个选项包含:
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 返回。
token 使用统计。
prompt_tokens(integer): 提示中的 token 数completion_tokens(integer): 补全中的 token 数,包含思考 tokentotal_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
}响应
{
"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 API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
可选键,用于防止同一请求被重复执行。请为每个请求发送一个新的唯一值(如 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