Saltar al contenido principal
idempotencyKey es una cadena opcional que indicas en un envío. Envía la misma clave otra vez y recibirás la tarea que creó el primer envío; no se encola trabajo nuevo ni se crea una nueva retención de créditos.
Sin clave no hay deduplicación: cada envío crea una tarea nueva. Indica una clave en todo lo que un cron o un worker con reintentos pueda enviar dos veces.
Construye la clave a partir de la unidad de trabajo, no del intento. Una clave como "{jobId}:{promptId}:{engine}" sale igual en cada reintento de ese trabajo.

Cómo trata cada endpoint una clave repetida

El endpoint de tarea individual mantiene una semántica de creación explícita: pediste crear una tarea que ya existe, así que recibes un conflicto. El error trae el id de la tarea existente en error.details.taskId, así que un envío que se quedó sin respuesta puede recuperarse sondeando ese id.
El lote de 500 tareas absorbe los duplicados como éxito, así que un worker puede reenviar un trabajo completo tras reiniciarse sin que el lote falle por los elementos que ya entraron.

Cuadrículas de ubicación

El idempotencyKey de la cuadrícula se convierte en su id (si lo omites se genera un UUID). La clave de la tarea de cada punto es <grid id>:r<row>c<col>. Enviar otra vez la misma cuadrícula con ese id devuelve los puntos existentes y admite solo los que faltan. Enviar una cuadrícula con otro centro, tamaño o radio con el mismo id hace fallar con RESOURCE_ALREADY_EXISTS los puntos cuyas coordenadas difieren; usa una clave nueva para una cuadrícula nueva.

Alcance y longitud

Las claves están limitadas a tu cuenta: otra cuenta puede usar la misma cadena sin colisionar con la tuya. No se exige formato UUID.

Relaciona resultados con envíos

Si no enviaste clave, idempotencyKey se omite del objeto de tarea en lugar de devolverse como null.

Vida útil de la clave

Una clave sigue reservada durante al menos 30 días después de la solicitud, incluso después de que la tarea se complete o falle y de que se cierre la ventana 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 nueva (por ejemplo, con el sufijo :r1) para una ejecución distinta del mismo trabajo.

Siguientes pasos

Lotes y cuadrículas

Los tres endpoints de envío en bloque, lado a lado.

Errores

Todos los códigos de error de solicitud.