核心指南
选择 API 格式
Chat Completions、Responses、Messages 和 Gemini 应该怎么选
一个 TokenLab API 密钥可以使用四种常见格式。现有应用已经使用哪一种，通常继续沿用即可；只有需要模型专属功能时才需要更换。
| 格式 | API | 适合 |
|---|---|---|
| Chat Completions | /v1/chat/completions | 已有 OpenAI 兼容聊天客户端，或希望兼容更多模型 |
| Responses | /v1/responses | 应用依赖 Responses 事件、后台响应或 Responses 工具 |
| Anthropic Messages | /v1/messages | 需要 Claude thinking、工具调用等 Messages 字段 |
| Gemini | /v1beta/models/:model:generateContent | 已在使用 Gemini 的 contents、parts、文件、缓存或工具 |
模型页面和 GET /v1/models/{model} 中的 tokenlab.accepted_request_formats 会列出可用格式。不是每个模型都支持全部四种。
Chat Completions
已有 OpenAI 兼容客户端，或想让同一套聊天代码适配更多模型时，可以使用 Chat Completions。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.chat.completions.create(
model="gpt-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)这个格式适合：
- 已有的 OpenAI 兼容聊天功能
- 标准消息历史和流式输出
- 模型支持的函数调用
其他 API 独有的字段不保证能在 Chat Completions 中使用。
Responses
只有模型的 accepted_request_formats 包含 openai_responses 时，才能使用 Responses API。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain why the sky is blue in two sentences.",
)
print(response.output_text)Responses 支持创建、读取、压缩、删除、流式输出、WebSocket 创建与续接；所选模型支持时也可以使用后台响应。删除用于移除已经保存的响应，不等于取消正在生成的内容。
Anthropic Messages
使用 Anthropic SDK 时，TokenLab 地址末尾不要加 /v1。
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)需要 Claude 专属字段时使用 Messages。Claude 的工具调用、thinking blocks 和 prompt cache 字段都应保留在这个格式中。
Gemini
Gemini 请求使用 TokenLab 主域名和 Gemini REST 路径。
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello!"}]}]
}'应用依赖 Gemini content parts、函数声明、文件、缓存或其他 Gemini 字段时，请使用这个格式。lowerCamelCase ProtoJSON 和原始 snake_case proto 名都能识别，但同一字段不要在一个请求里同时使用两种拼写。
一段对话只用一种格式
Messages、Responses、Chat Completions 和 Gemini 表示消息历史与工具调用的方式不同。不要在同一段对话中混用。需要迁移已有历史时，请在自己的应用里完成转换和校验，再发送下一条请求。
未知字段
TokenLab 可能会保留未识别的字段，但这不代表每个模型都能接受。只有模型文档明确支持、并且应用能处理“不支持字段”错误时，才能把某个功能作为稳定依赖。