TokenLab

檔案與批次

建立批次 (Create Batch)

從已上傳的 JSONL 檔案建立批次。

POST
/v1/batches

概覽

上傳一個 purpose=batch 的 JSONL 檔案,然後使用其 ID 作為 input_file_id。已完成的批次會回傳輸出與錯誤檔案的 ID。

輸入檔案

該檔案為 JSONL 格式:每行一個請求,最多 50,000 行且不超過 200 MiB。對於 /v1/embeddings,所有行中的輸入總數也限制為 50,000。每一行需要包含:

  • custom_id:一個字串,在檔案中必須是唯一的。
  • method:POST。
  • url:與批次 endpoint 相同的值。
  • body:請求主體,包含 model。
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}}

注意事項

  • 批次輸入檔案必須使用 purpose=batch。
  • completion_window 為 24h,這是預設值也是唯一值。
  • metadata 最多可包含 16 個字串對:鍵(key)最多 64 個字元,值(value)最多 512 個字元。
  • output_expires_after 設定結果檔案的過期時間:anchor 可為 created_at 或 completed_at,seconds 最多為 30 天。
  • 輸出順序可能與輸入順序不同。請透過 custom_id 來匹配每個結果。
  • 批次項目內不支援串流(Streaming)。
  • 支援的項目端點為 /v1/chat/completions 和 /v1/embeddings。不支援 /v1/responses。
  • 建立批次時會預留預估費用。若餘額不足,將回傳 402。
  • 無效的檔案會回傳 400,並將 param 設定為 input_file_id,訊息中會指出錯誤所在的行數。

範例

請求

cURL
curl -X POST "https://api.tokenlab.sh/v1/batches" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

批次價格可能與同步請求不同。請查看最終帳單以確認費用。

回應範例

回應

200 OK
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1706000000
}

重要欄位

idstring
批次 ID。
statusstring
批次狀態。
output_file_idstring|null
完成後的輸出檔案 ID。

授權

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"

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json