Skip to main content
idempotencyKey é uma string opcional fornecida por quem chama que torna um envio deduplicável. Envie a mesma chave duas vezes e o segundo envio aponta para a tarefa criada pelo primeiro, sem enfileirar trabalho novo.
Sem ela, não há deduplicação: cada envio cria uma tarefa nova. É uma escolha válida para consultas avulsas e a escolha errada para qualquer coisa que um cron ou um worker com novas tentativas possa enviar duas vezes.
Uma boa chave é derivada de forma determinística do próprio trabalho, não da tentativa. Ao compor os identificadores que definem a unidade de trabalho, como "{jobId}:{promptId}:{engine}", uma nova tentativa reproduz naturalmente a mesma chave.

​
Individual e lote diferem de propósito

É o único ponto em que os dois endpoints divergem, e costuma confundir.
O endpoint individual mantém a semântica de criação explícita: você pediu para criar uma tarefa, a tarefa já existe, isso é um conflito e você precisa saber. O endpoint de lote absorve duplicatas como sucesso. Quem chama costuma ser um worker que reenvia um job inteiro depois de reiniciar, e marcar como falho um lote de 500 itens porque uma chave já estava na fila anularia o propósito das chaves de idempotência. O results[i].task devolvido é a tarefa existente, então seu mapeamento de tarefas continua funcionando.

​
Relacionando resultados aos envios

São dois identificadores independentes, e você quer os dois:
​
integer
Corresponde 1:1 por posição ao seu array de entrada. Use-o para relacionar a resposta do lote às tarefas enviadas.
​
string
Devolvida sem alterações. Use-a para relacionar o webhook, que chega minutos depois, fora de ordem e sem referência ao seu array original.
Se você não informou idempotencyKey, o campo é omitido do objeto da tarefa em vez de retornar null. Internamente a tarefa usa seu próprio uuid como chave, que é único por construção e por isso nunca deduplica.

​
Vida útil da chave

As chaves de tarefas com retenção permanente continuam reservadas depois da conclusão, da falha e da janela pública de polling de 24 horas. Um 404 no polling não libera a chave. Use a mesma chave nas novas tentativas de transporte de um envio e uma nova chave de execução (por exemplo, com o sufixo :r1) para uma execução separada. O formato UUID não é obrigatório. Registros que já tinham sido movidos para o histórico legado antes de a retenção permanente ser ativada não reservam chaves retroativamente.