檔案與批次
建立批次 (Create Batch)
從已上傳的 JSONL 檔案建立批次。
概覽
上傳一個 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 -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"
}'批次價格可能與同步請求不同。請查看最終帳單以確認費用。
回應
{
"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