文本
创建消息
使用 Anthropic Messages API 格式创建消息
概述
该接口接受原生 Anthropic Messages 格式,因此 Anthropic SDK 及基于它们的工具只需换成 TokenLab 的 Base URL 即可使用。凡是 accepted_request_formats 包含 anthropic_messages 的模型都可使用,包括 Claude 模型和部分其他模型。
messages 放 user 和 assistant 轮次。系统指令放在顶层 system 字段。必须提供 max_tokens。如果消息使用 OpenAI 风格的 system 或 tool 等 role,请改用 Chat Completions。
Anthropic SDK 的 Base URL:https://api.tokenlab.sh(不带 /v1 后缀)
请求头
您的 TokenLab API 密钥。通过 x-api-key 或 Authorization: Bearer <API_KEY> 任选其一发送。两者同时发送且值不同时,TokenLab 使用 x-api-key。
Anthropic API 版本。Anthropic SDK 会自动发送;直接调用 API 时请使用 2023-06-01。
Anthropic beta 功能名称,多个名称用逗号分隔。TokenLab 会转发该请求头,beta 功能是否生效取决于模型。内容引用 file_id 时需要 files-api-2025-04-14。
请求体
可选参数的支持情况、取值和默认值取决于所选模型。设置采样、推理或工具选项前,请查看其模型详情。
支持 anthropic_messages 格式的模型 ID。请查看其模型详情确认当前能力。
包含 role(user 或 assistant)和 content 的消息对象数组。最多 100,000 条消息。
content 可以是纯字符串,也可以是内容块数组。传图片时请使用结构化内容块,而不是把图片 URL 或 Base64 直接写进纯文本里。支持的模型还接受 tool_use、tool_result、thinking、document 等其他原生内容块。
内容块示例:
- 文本块:
{ "type": "text", "text": "请描述这张图片" } - URL 图片块:
{ "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } } - Base64 图片块:
{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
要生成的最大 token 数。必填:TokenLab 不会补默认值。可用上限取决于模型,见其模型详情中的 max_output_tokens。该值越大,请求运行期间 TokenLab 从余额中预留的金额越多;余额不足以覆盖预留时返回 402。
系统提示词,可以是字符串或文本内容块数组,单独放在顶层,不放入 messages 数组。
采样温度。是否支持、允许的取值和默认值取决于所选模型;省略此字段即可使用模型默认值。
false以服务器发送事件(SSE)流的形式返回响应。见流式输出。
原生 thinking 配置,例如 {"type":"enabled","budget_tokens":10000}。支持的模式、预算以及与其他参数的组合取决于所选模型。对于已知拒绝手动预算的模型,TokenLab 会把 {"type":"enabled"} 按自适应思考运行,并忽略 budget_tokens。
模型可用的工具。支持情况取决于所选模型。
原生工具选择对象,例如 {"type":"auto"}。支持的类型取决于所选模型。
提示词缓存标记,例如 {"type":"ephemeral"};加上 "ttl": "1h" 表示缓存一小时。放在顶层表示开启自动缓存。也可以设置在 system 块、tools 和内容块上。支持情况取决于模型;支持缓存的模型在 capabilities 中列出 prompt-cache。
Top P 采样参数。建议只调整 temperature 或 top_p 其中一个。支持情况取决于所选模型。
每个 token 仅从前 K 个选项中进行采样。支持情况取决于所选模型。
自定义停止序列,当命中时模型将停止生成。最多 8,191 项。
Anthropic 格式的请求元数据。user_id 是您的终端用户的不透明标识。
只有 auto 和 standard_only 会生效。TokenLab 只按标准档计价,其他取值会被忽略。
响应
唯一的消息标识符。
始终为 message。
始终为 assistant。
内容块数组,例如 text、thinking 或 tool_use。
生成该响应的模型。
停止生成的原因,例如 end_turn、max_tokens、stop_sequence 或 tool_use。模型也可能返回其他值,例如 refusal。
触发停止的停止序列,没有则为 null。
token 使用情况,包含 input_tokens 和 output_tokens。模型报告提示词缓存 token 时,usage 还包含 cache_creation_input_tokens 和 cache_read_input_tokens。
每个响应的 request-id 和 X-Request-ID 响应头都带有请求 ID。联系支持时请提供它。
请求
curl -X POST "https://api.tokenlab.sh/v1/messages" \
-H "x-api-key: sk-your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": "You are a helpful assistant.",
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'响应
{
"id": "msg_abc123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"model": "claude-sonnet-5",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 15,
"output_tokens": 10
}
}图片输入示例
对于支持视觉能力的 Claude 模型,请将图片放在 messages[].content 中,作为结构化图片内容块传入。
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片。"
},
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/demo.jpg"
}
}
]
}
]
}{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片。"
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ..."
}
}
]
}
]
}扩展思考示例
请使用具有 reasoning 能力的模型。按模型限制调整 max_tokens 和 budget_tokens;部分模型需要不同的 thinking 配置。
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{"role": "user", "content": "Solve this math problem..."}]
)
for block in message.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "text":
print(f"Response: {block.text}")流式输出
设置 "stream": true 后,会收到 Anthropic 服务器发送事件:message_start、content_block_start、content_block_delta、content_block_stop、message_delta 和 message_stop。token 用量出现在 message_start 和 message_delta 中。
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)- 模型处理期间,流里可能出现
: keep-alive这样的 SSE 注释行,SDK 会忽略它们。 - 出现故障时 HTTP 状态可能已经是
200。流开始后的故障会以event: error事件送达,错误体与下文相同。
错误
错误使用 Anthropic 错误格式。request_id 是 TokenLab 请求 ID。部分错误还会带有 code、hint 等字段。
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
},
"request_id": "req_01JEXAMPLE"
}| 状态码 | error.type | 常见原因 |
|---|---|---|
| 400 | invalid_request_error | 字段缺失或无效、模型不存在,或模型不接受 Messages 格式 |
| 401 | authentication_error | API 密钥缺失或无效 |
| 402 | billing_error | 余额不足以覆盖请求(error.code 为 insufficient_balance)。API 密钥达到消费上限时也返回 402,此时 error.code 为 quota_exceeded,error.type 为 rate_limit_error |
| 403 | permission_error | API 密钥无权使用所请求的模型,或账户已被暂停或受限 |
| 409 | conflict_error | 使用相同 Idempotency-Key 重试。见用幂等键安全重试 |
| 413 | request_too_large | 请求输入过大 |
| 429 | rate_limit_error | 请求过多 |
| 500、502、503 | api_error 或 overloaded_error | 请求未能完成,或当前没有可用于该请求的路由,请稍后重试 |
| 504 | timeout_error | 请求超时 |
关联接口
授权
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
application/json
application/json
application/json
application/json