三个端点对比
选择哪一个
- 不超过 500 个任务，且你自己处理重试：
POST /v1/async/task/batch。响应中包含所有任务 id。 - 任务数超过套餐并发，或每天运行数千个任务的作业：
POST /v1/batches。服务器保存项目，并在套餐限制和各引擎队列允许时逐步送入，你无需自己重试429或503。 - 从某地周围的多个点位提同一个提示词：
POST /v1/async/task/grid。
POST /v1/async/task/batch
发送最多 500 个任务请求组成的数组（参考）。可以混用引擎。
200。results[i].index 对应你数组中的位置，每个结果包含 task 或 error 之一：
重复的
idempotencyKey 会以成功形式返回已存在的任务。参见幂等性。
POST /v1/batches
发送最多 10,000 个项目（参考）。每个项目接受任务字段 taskType、payload、priority 和 idempotencyKey，以及可选的 customId（最多 128 个字符），它会在结果中原样返回。webhook.url 设在批次上，而不是项目上。
202，返回批次。最初的项目已经提交：
信封规则
全有或全无的校验
在存储任何内容之前，每个项目都会经过与单个任务相同的检查：字段、密钥范围、私有引擎、专用端点、地区和payload.location。任一项目失败，响应即为 400 VALIDATION_ERROR，不存储任何内容，details 最多列出 50 个失败项目：
项目如何运行
当套餐限制和引擎队列有空位时，批次会把项目作为任务释放。各账户轮流进行，因此一个大批次不会阻塞其他账户的小批次。每个释放的项目都经过与单个任务相同的准入流程：冻结积分，并计入密钥的每日积分上限。 项目被拒绝时，由错误码决定后续处理：
没有待处理项目且所有任务都结束后，批次变为
COMPLETED。设置了 webhook.url 时，服务器随后发送 batch.completed 事件。
读取进度与结果
GET /v1/batches/{id} 返回批次及按项目状态统计的 counts：pending、queued、processing、completed、failed、rejected。轮询它也会推动待处理项目继续前进。
GET /v1/batches/{id}/items 按提交顺序列出项目：
REJECTED 项目带有 error: { code, message }。结果正文只在异步任务的 24 小时轮询窗口内返回。另请参阅获取批次和列出批次项目。
POST /v1/async/task/grid
从中心周围方形网格的每个点位提同一个提示词（参考）。每个点位成为一个以该点为 payload.location 的任务，因此引擎必须支持位置：CHATGPT、GEMINI、GOOGLE、AIMODE 或 GOOGLE_SERP。不要自己发送 payload.location。
第 0 行是北边，第 0 列是西边。响应返回
grid（含 id 和 spacingMeters）、summary，以及按行排序的 points，每个点位包含 row、col、location，以及 task 或 error 之一。
中心点会最先、单独被准入。如果它被拒绝（例如 422 LOCATION_UNSUPPORTED、403 KEY_SCOPE_DENIED、402 INSUFFICIENT_CREDITS 或套餐已满），该错误就是整个网格的响应，不创建任何任务。中心点之后因容量被拒的点位会以 success: false 就地失败。
用 GET /v1/async/task/grid/{id} 读取网格。加上 ?include=response 可获取已结束任务的结果。从未被准入的点位不会出现，其他账户的网格 id 返回 404。以同一 id 重新发送同一网格只会准入缺失的点位；参见幂等性。
下一步
幂等性
各端点如何处理重复的键。
积分与限制
套餐并发与提交节奏。