TokenLab

檔案與批次

建立訊息批次 (Create Message Batch)

建立一組以非同步方式執行的 Messages 請求批次。

POST
/v1/messages/batches

概覽

單次呼叫最多可發送 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
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
訊息批次 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