檔案與批次
建立訊息批次 (Create Message Batch)
建立一組以非同步方式執行的 Messages 請求批次。
概覽
單次呼叫最多可發送 100,000 個 Messages 請求。該批次會以非同步方式執行。回應會立即返回,且 processing_status 將被設為 in_progress。請持續 檢索該批次 直到其狀態變為 ended,然後 取得結果。
注意事項
requests中的每個項目都必須包含custom_id和params。params接受與 建立訊息 (Create Message) 相同的欄位,包括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
訊息批次 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 金鑰。
位置: header
請求標頭
X-TokenLab-Delivery-Policy?string
單次請求傳遞策略。會覆寫 API key 與 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