批量任务（暂未提供服务）

通过批量端点异步处理大量请求，享受批量折扣定价。完整流程与配额限制见批量推理指南。本页给出全部相关 REST 端点的请求/响应规范。

创建批量任务

POST /v1/batches

请求体

input_file_idstring必填

已上传到 /v1/files（purpose=batch）的输入文件 ID。每行一个请求对象。

endpointenum必填

目标接口路径，例如 /v1/chat/completions、/v1/embeddings。

completion_windowenum必填

完成窗口，目前支持 "24h"。窗口期内未完成的请求会被标记 expired。

metadataobject可选

自定义键值对（最多 16 项），用于业务侧标记任务来源。

响应

示例 — 201 已创建

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-xyz789",
  "status": "validating",
  "completion_window": "24h",
  "created_at": 1744828800,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 }
}

查询批量任务

GET /v1/batches/{batch_id}

路径参数

batch_idstring · path必填

批量任务 ID。

响应字段（全部状态）

statusenum

validating / in_progress / finalizing / completed / failed / expired / cancelling / cancelled。

output_file_idstring可选

完成后可下载的结果文件 ID（每行对应一条响应，含 custom_id）。

error_file_idstring可选

失败请求的错误明细文件 ID。

request_countsobject

{ total, completed, failed } 实时进度计数。

created_at / in_progress_at / completed_at / failed_at / cancelled_atinteger

各状态切换时的 UNIX 时间戳。

取消批量任务

POST /v1/batches/{batch_id}/cancel

将任务状态置为 cancelling，调度器停止派发新请求；已完成的部分仍可通过 output_file_id 下载。最终状态变为 cancelled。

列出批量任务

GET /v1/batches

查询参数

limitinteger · query20

单页返回条数，1 – 100。

afterstring · query可选

游标分页：传上一页最后一项的 id，按创建时间倒序翻页。