文本

创建消息

使用 Anthropic Messages API 格式创建消息

POST
/v1/messages

概述

该接口接受原生 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 后缀)

请求头

x-api-keystringheader

您的 TokenLab API 密钥。通过 x-api-key 或 Authorization: Bearer <API_KEY> 任选其一发送。两者同时发送且值不同时,TokenLab 使用 x-api-key。

anthropic-versionstringheader

Anthropic API 版本。Anthropic SDK 会自动发送;直接调用 API 时请使用 2023-06-01。

anthropic-betastringheader

Anthropic beta 功能名称,多个名称用逗号分隔。TokenLab 会转发该请求头,beta 功能是否生效取决于模型。内容引用 file_id 时需要 files-api-2025-04-14。

请求体

可选参数的支持情况、取值和默认值取决于所选模型。设置采样、推理或工具选项前,请查看其模型详情。

modelstring必填

支持 anthropic_messages 格式的模型 ID。请查看其模型详情确认当前能力。

messagesarray必填

包含 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..." } }
max_tokensinteger必填

要生成的最大 token 数。必填:TokenLab 不会补默认值。可用上限取决于模型,见其模型详情中的 max_output_tokens。该值越大,请求运行期间 TokenLab 从余额中预留的金额越多;余额不足以覆盖预留时返回 402。

systemstring | array

系统提示词,可以是字符串或文本内容块数组,单独放在顶层,不放入 messages 数组。

temperaturenumber

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

streamboolean默认值: false

以服务器发送事件(SSE)流的形式返回响应。见流式输出。

thinkingobject

原生 thinking 配置,例如 {"type":"enabled","budget_tokens":10000}。支持的模式、预算以及与其他参数的组合取决于所选模型。对于已知拒绝手动预算的模型,TokenLab 会把 {"type":"enabled"} 按自适应思考运行,并忽略 budget_tokens。

toolsarray

模型可用的工具。支持情况取决于所选模型。

tool_choiceobject

原生工具选择对象,例如 {"type":"auto"}。支持的类型取决于所选模型。

cache_controlobject

提示词缓存标记,例如 {"type":"ephemeral"};加上 "ttl": "1h" 表示缓存一小时。放在顶层表示开启自动缓存。也可以设置在 system 块、tools 和内容块上。支持情况取决于模型;支持缓存的模型在 capabilities 中列出 prompt-cache。

top_pnumber

Top P 采样参数。建议只调整 temperature 或 top_p 其中一个。支持情况取决于所选模型。

top_kinteger

每个 token 仅从前 K 个选项中进行采样。支持情况取决于所选模型。

stop_sequencesarray

自定义停止序列,当命中时模型将停止生成。最多 8,191 项。

metadataobject

Anthropic 格式的请求元数据。user_id 是您的终端用户的不透明标识。

service_tierstring

只有 auto 和 standard_only 会生效。TokenLab 只按标准档计价,其他取值会被忽略。

响应

idstring

唯一的消息标识符。

typestring

始终为 message。

rolestring

始终为 assistant。

contentarray

内容块数组,例如 text、thinking 或 tool_use。

modelstring

生成该响应的模型。

stop_reasonstring

停止生成的原因,例如 end_turn、max_tokens、stop_sequence 或 tool_use。模型也可能返回其他值,例如 refusal。

stop_sequencestring | null

触发停止的停止序列,没有则为 null。

usageobject

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!"}
    ]
  }'

响应

Response
{
  "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常见原因
400invalid_request_error字段缺失或无效、模型不存在,或模型不接受 Messages 格式
401authentication_errorAPI 密钥缺失或无效
402billing_error余额不足以覆盖请求(error.code 为 insufficient_balance)。API 密钥达到消费上限时也返回 402,此时 error.code 为 quota_exceeded,error.type 为 rate_limit_error
403permission_errorAPI 密钥无权使用所请求的模型,或账户已被暂停或受限
409conflict_error使用相同 Idempotency-Key 重试。见用幂等键安全重试
413request_too_large请求输入过大
429rate_limit_error请求过多
500、502、503api_error 或 overloaded_error请求未能完成,或当前没有可用于该请求的路由,请稍后重试
504timeout_error请求超时

关联接口

授权

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

application/json

application/json

application/json

application/json