创建 Batch

POST /api/v1/forward/batches Forward 校验输入文件与 JSONL 行格式后，在闲时窗口内自动调度执行，完成后生成 output.jsonl 和 error.jsonl 供下载。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT>`
Content-Type	是	`application/json`
Idempotency-Key	否	有副作用请求可选的幂等键。

前置准备：上传输入文件

创建 Batch 需要先准备 JSONL 格式的输入文件，然后通过 CAS Files API 上传获得 file_id。 JSONL 格式：每行一个 JSON 对象，代表一个独立任务：

{"custom_id": "task-001", "template_id": "tmpl_example001", "identity_id": "idn_example001", "body": {"input": "你好"}}
{"custom_id": "task-002", "template_id": "tmpl_example001", "identity_id": "idn_example001", "body": {"input": "帮我写一首关于夏天的短诗"}}

字段	类型	必填	说明
`custom_id`	string	是	调用方自定义标识，单 Batch 内唯一，用于结果文件行对应。
`template_id`	string	是	Forward Template ID，指定执行模板。
`identity_id`	string	是	Forward Identity ID，指定执行身份。
`body`	object	是	传给 Session 的请求体，结构取决于 Template 定义。常见格式：`{"input": "用户输入内容"}`。

上传文件：

curl -X POST 'https://api.qoder.com/api/v1/cloud/files' \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@batch_input.jsonl" \
  -F "purpose=session_resource"

purpose 必须为 session_resource，否则后续下载可能失败。

返回的 id 即为创建 Batch 请求中的 input_file_id。

请求体参数

参数	类型	是否必填	说明
input_file_id	string	是	通过 Files API 上传的 JSONL 文件 ID。
completion_window	string	是	完成窗口：`24h`、`48h`、`72h`。超时后 Batch 自动进入 `expired` 状态。
metadata	object	否	调用方业务元数据，最多 16 个 key；value 可为任意 JSON 类型；整体序列化后 ≤ 2KB，key ≤ 64 字符，且不得包含 NUL（U+0000）。

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/batches' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_batch_001" \
  -d '{
  "input_file_id": "file_input001",
  "completion_window": "24h",
  "metadata": {
    "source": "data_pipeline",
    "job_id": "12345"
  }
}'

示例响应

HTTP 200 OK

{
  "id": "batch_example001",
  "object": "batch",
  "status": "validating",
  "input_file_id": "file_input001",
  "completion_window": "24h",
  "created_at": "2026-07-07T07:25:01Z",
  "expires_at": "2026-07-08T07:25:01Z",
  "request_counts": {
    "total": 0,
    "pending": 0,
    "running": 0,
    "completed": 0,
    "failed": 0,
    "cancelled": 0,
    "expired": 0
  },
  "usage": null
}

创建成功后 Batch 立即进入 validating，校验通过转 queued；output_file_id / error_file_id 在任务终态后才出现，创建响应中省略。

响应字段

字段	类型	说明
id	string	Batch ID，前缀 `batch_`。
object	string	固定为 `batch`。
status	string	Batch 状态，见状态说明。
input_file_id	string	输入 JSONL 文件 ID。
completion_window	string	完成窗口：`24h`、`48h`、`72h`。
created_at	string	创建时间，RFC 3339。
expires_at	string	过期时间，`created_at` + `completion_window`。
request_counts	object	任务计数聚合。
usage	object/null	预留字段，v1 固定为 `null`。
metadata	object	调用方业务元数据。

Batch 状态

状态	说明	类型
`validating`	正在校验输入文件和 JSONL 行格式。	非终态
`queued`	校验通过，等待闲时窗口激活。	非终态
`processing`	正在执行任务。	非终态
`cancelling`	取消中，等待 running task 结束。	非终态
`expiring`	过期中，等待 running task 结束。	非终态
`finalizing`	正在生成输出文件。	非终态
`completed`	所有任务执行完毕，输出文件已生成。	终态
`failed`	文件校验失败或不可恢复的系统错误。	终态
`cancelled`	用户取消完成。	终态
`expired`	`completion_window` 到期。	终态

Request Counts

字段	类型	说明
total	integer	总行数（含校验失败行）。
pending	integer	等待执行的行数。
running	integer	正在执行的行数。
completed	integer	执行成功的行数。
failed	integer	永久失败的行数（含校验失败）。
cancelled	integer	因取消而终止的行数。
expired	integer	因过期而终止的行数。

total = pending + running + completed + failed + cancelled + expired 始终成立。

校验规则

创建 Batch 阶段拦截以下错误，不入队执行：

JSON 解析失败 → 该行标记 failed
必填字段缺失 → 该行标记 failed
custom_id 重复 → 该行标记 failed
always_ask/always_deny 工具权限策略 → 该行标记 failed（无人值守场景不允许）

校验失败的行不阻塞其他行，统一写入 error.jsonl。

错误码

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_request`	`input_file_id` 缺失、`completion_window` 非法、`metadata` 超限。
429	`rate_limit_error`	`rate_limit_exceeded`	用户未完成 Batch 数量达到上限。
401	`authentication_error`	`authentication_required`	PAT 无效或已过期。

注意事项

单批次最大 10,000 行 JSONL。
全局并发上限 50 个 task。
调度在闲时窗口（默认 22:00~08:00，后台可配）内执行。
客户端创建 Batch 后，应通过 GET /api/v1/forward/batches/{batch_id} 轮询到终态。

快速上手

构建 Agent

配置 Agent 环境

委派任务给 Agent

管理 Agent 上下文

最佳实践

API 参考

创建 Batch

请求头

前置准备：上传输入文件

请求体参数

示例请求

示例响应

响应字段

Batch 状态

Request Counts

校验规则

错误码

注意事项

相关

查询 Batch 详情

取消 Batch

​请求头

​前置准备：上传输入文件

​请求体参数

​示例请求

​示例响应

​响应字段

​Batch 状态

​Request Counts

​校验规则

​错误码

​注意事项

​相关

查询 Batch 详情

取消 Batch

请求头

前置准备：上传输入文件

请求体参数

示例请求

示例响应

响应字段

Batch 状态

Request Counts

校验规则

错误码

注意事项

相关