文件与批处理

创建批处理

使用已上传的 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 个字符串键值对:键最长 64 个字符,值最长 512 个字符。
  • output_expires_after 设置结果文件的过期时间:anchor 为 created_at 或 completed_at,seconds 最多 30 天。
  • 输出顺序可能与输入不同,请用每行的 custom_id 对应结果。
  • 批处理项内不支持流式传输。
  • 支持的批处理项端点为 /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 Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json