文件与批处理

创建 Message Batch

创建一批异步运行的 Messages 请求。

POST
/v1/messages/batches

概述

一次调用最多提交 100,000 条 Messages 请求。批次异步运行,响应会立即返回,processing_status 为 in_progress。请获取批次直到状态变为 ended,再获取结果。

说明

  • requests 中的每一项包含 custom_id 和 params。params 的字段与创建消息相同,包括 max_tokens。各项不能使用 speed: "fast"。
  • custom_id 由 1 到 64 个字母、数字、下划线或连字符组成,在批次内必须唯一。
  • 批次中的每个模型都必须支持批处理。如果某个模型不支持,或没有单一路由能同时服务批次里的所有模型,TokenLab 会以 400 拒绝整个请求。
  • TokenLab 在受理批次时按估算费用预留额度,余额不足以覆盖时返回 402。批次结束后,TokenLab 按成功请求的用量结算。批处理价格可能与同步请求不同。
  • 如果某项引用了 file_id 内容,请发送 anthropic-beta: files-api-2025-04-14。
  • 发送 Idempotency-Key 可以安全重试超时的创建请求。见用幂等键安全重试。

示例

请求

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

响应示例

响应

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

重要字段

idstring
Message Batch ID。用它获取、取消或删除批次,以及获取结果。
processing_statusstring
in_progress、canceling 或 ended。
request_countsobject
处于 processing、succeeded、errored、canceled 或 expired 状态的请求数量。
expires_atstring
批次的过期时间。到期时尚未完成的请求以 expired 结束。
results_urlstring|null
结果的 URL。批次结束前为 null。

授权

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 错误。超过 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