文件与批处理
创建 Message Batch
创建一批异步运行的 Messages 请求。
概述
一次调用最多提交 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 -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."}]
}
}
]
}'响应
{
"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