Skip to main content
idempotencyKey es una cadena opcional que aporta el cliente y hace que un envío se deduplique. Envía la misma clave dos veces y el segundo envío se resuelve en la tarea que creó el primero, sin encolar trabajo nuevo.
Si la omites no hay deduplicación: cada envío crea una tarea nueva. Es una elección válida para consultas puntuales y la equivocada para cualquier cosa que un cron o un worker con reintentos pueda enviar dos veces.
Una buena clave se deriva de forma determinista del trabajo, no del intento. Si compones los identificadores que definen la unidad de trabajo, como "{jobId}:{promptId}:{engine}", un reintento reproduce la misma clave de forma natural.

​
Individual y lote difieren a propósito

Es el único punto en que los dos endpoints divergen, y suele confundir.
El endpoint individual mantiene una semántica de creación explícita: pediste crear una tarea, la tarea ya existe, eso es un conflicto y debes saberlo. El endpoint de lote absorbe los duplicados como éxito. Su cliente habitual es un worker que reenvía un trabajo completo tras reiniciarse, y marcar como fallido un lote de 500 elementos porque una clave ya estaba en cola anularía el sentido de las claves de idempotencia. El results[i].task que recibes es la tarea existente, así que tu mapeo de tareas sigue resolviéndose.

​
Relacionar resultados con envíos

Hay dos identificadores independientes y te conviene usar ambos:
​
integer
Corresponde 1:1 por posición con tu array de entrada. Úsalo para relacionar la respuesta del lote con las tareas que enviaste.
​
string
Se devuelve tal cual. Úsalo para relacionar el webhook, que llega minutos después, desordenado y sin referencia a tu array original.
Si no enviaste idempotencyKey, el campo se omite del objeto de tarea en lugar de devolverse como null. Internamente la tarea usa su propio uuid como clave, que es único por construcción y por tanto nunca deduplica.

​
Vida de la clave

Las claves de tareas con retención permanente siguen reservadas tras la finalización, el fallo y la ventana pública de sondeo de 24 horas. Un 404 en el sondeo no libera la clave. Usa la misma clave para los reintentos de transporte de un envío y una clave de ejecución nueva (por ejemplo, con el sufijo :r1) para una ejecución distinta. No se exige formato UUID. Los registros que ya se habían movido al historial heredado antes de activarse la retención permanente no reservan claves de forma retroactiva.