跳转到主要内容
idempotencyKey 是你在提交时可选设置的字符串。再次发送同一个键,你会拿到第一次提交创建的任务;不会排入新的工作,也不会新增积分冻结。
没有键就不会去重:每次提交都会创建新任务。对 cron 作业或会重试的 worker 可能重复发送的内容,请设置键。
键应由工作单元而非某次尝试生成。像 "{jobId}:{promptId}:{engine}" 这样的键,在该工作的每次重试中都相同。

各端点如何处理重复的键

单任务端点保留显式创建语义:你要求创建一个已存在的任务,因此会得到冲突。错误中的 error.details.taskId 是既有任务的 id,提交响应丢失时可用它查询结果。
500 任务的批量端点把重复吸收为成功,因此 worker 重启后可以重新发送整个作业,而不会因为已经提交过的项目导致批量请求失败。

位置网格

网格的 idempotencyKey 会成为它的 id(省略时自动生成 UUID)。每个点位的任务键为 <grid id>:r<row>c<col>。以该 id 再次发送同一网格,会返回已存在的点位,只接纳缺失的点位。以同一 id 发送中心、尺寸或半径不同的网格时,坐标不同的点位会以 RESOURCE_ALREADY_EXISTS 失败;新网格请使用新键。

范围与长度

键的作用域是你的账户:其他账户可以使用相同的字符串,不会与你的冲突。 不要求 UUID 格式。

将结果与提交对应

如果没有发送键,任务对象中会省略 idempotencyKey,而不是返回 null。

键的生命周期

键在请求后至少保持占用 30 天,任务完成或失败后、24 小时轮询窗口关闭后也是如此。轮询返回 404 不会释放键。同一次提交的传输重试请使用同一个键;同一工作的另一次独立运行请使用新键(例如追加 :r1 后缀)。

下一步

批次与网格

三个批量端点的对比。

错误

所有请求错误码。