API: 批量任务管理 (Batches)

Batch Tasks

Create and manage batch inference tasks for offline processing at lower cost.

创建批量任务

端点:POST /v1/batches

Request Body

input_file_id (string, required)

已上传的数据集文件 ID,详见 上传文件。

endpoint (string, required)

批量任务使用的 API 端点,当前支持:/v1/chat/completions。

completion_window (string, required)

任务完成时限,当前固定为 24h。

metadata (object, optional)

可选的元数据,可附加任意键值对用于查询和管理。

代码示例

curl --request post \
  --url https://khb.net.cn/v1/batches \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "input_file_id": "file-jkvytbjtow",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {
      "project": "customer-service",
      "tag": "weekly-eval"
    }
  }'

Response Body

{
  "id": "batch_abc123def456",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-jkvytbjtow",
  "completion_window": "24h",
  "status": "validating",
  "created_at": 1741685396
}

获取批量任务列表

端点:GET /v1/batches

Query Parameters

• limit:返回数量,默认 20,最大 100
• after:分页游标(上一页最后一条的 ID)

Response Body

{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123def456",
      "endpoint": "/v1/chat/completions",
      "status": "completed",
      "created_at": 1741685396,
      "completed_at": 1741689120
    }
  ],
  "has_more": false
}

获取批量任务详情

端点:GET /v1/batches/{batch_id}

Path Parameters

• batch_id:批量任务 ID

Response Body

{
  "id": "batch_abc123def456",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-jkvytbjtow",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-output-xyz",
  "error_file_id": null,
  "request_counts": {
    "total": 1000,
    "completed": 998,
    "failed": 2
  },
  "created_at": 1741685396,
  "completed_at": 1741689120
}

任务状态说明

结果下载

任务完成后,通过 output_file_id 获取结果文件 ID,使用 GET /v1/files/{file_id}/content 下载结果。结果为 .jsonl 格式,URL 有效期 1 个月。

错误码