Skip to main content
idempotencyKey 是调用方可选提供的字符串，使提交具备去重能力。用同一个键发送两次，第二次提交会解析到第一次 创建的任务，而不会排入新的工作。
省略它就没有去重，每次提交都会创建新任务。对一次性查询这是合理的选择；对 cron 或会重试的 worker 可能 重复提交的工作，则是错误的选择。
好的键应由工作本身而非某次尝试确定地生成。把定义工作单元的标识组合起来，如 "{jobId}:{promptId}:{engine}"，重试时自然会得到同一个键。

​
单个与批量有意不同

这是两个端点唯一的差异之处，也常让人踩坑。
单任务端点保留显式创建语义：你要求创建任务，而任务已存在，这就是冲突，你应当知道。 批量端点把重复吸收为成功。它的调用方通常是重启后重新提交整个作业的 worker，因为一个键已在队列中就把 500 项的批次判为失败，会让幂等键失去意义。你拿到的 results[i].task 是已存在的任务，因此任务映射依然成立。

​
将结果与提交对应

有两个相互独立的句柄，你两个都需要：
​
integer
与输入数组按位置一一对应。用它把批量响应与你发送的任务对应起来。
​
string
原样回传。用它对应 webhook，webhook 会在几分钟后乱序到达，且不引用你的原始数组。
如果没有提供 idempotencyKey，该字段会从任务对象中省略，而不是返回 null。内部任务会以自身 uuid 作为键， 它天然唯一，因此永远不会去重。

​
键的生命周期

永久保留的任务，其键在完成、失败以及 24 小时公开轮询窗口之后仍保持占用。轮询返回 404 并不会释放键。同一次 提交的传输重试请使用同一个键；单独的一次运行请使用新的执行键（例如追加 :r1 后缀）。不要求 UUID 格式。 在启用永久保留之前已移入旧历史的记录不会追溯占用键。