Skip to main content
idempotencyKey est une chaîne facultative fournie par l’appelant qui rend une soumission dédupliquante. Envoyez deux fois la même clé et la seconde soumission renvoie à la tâche créée par la première au lieu de mettre en file un nouveau travail.
Sans elle, il n’y a aucune déduplication : chaque soumission crée une nouvelle tâche. C’est un choix légitime pour des requêtes ponctuelles, et le mauvais choix pour tout ce qu’un cron ou un worker qui réessaie pourrait soumettre deux fois.
Une bonne clé se déduit de manière déterministe du travail lui-même, pas de la tentative. En composant les identifiants qui définissent l’unité de travail, par exemple "{jobId}:{promptId}:{engine}", une nouvelle tentative reproduit naturellement la même clé.

​
Unitaire et lot diffèrent volontairement

C’est le seul point où les deux endpoints divergent, et il piège souvent.
L’endpoint unitaire garde une sémantique de création explicite : vous avez demandé à créer une tâche, elle existe déjà, c’est un conflit et vous devez le savoir. L’endpoint de lot absorbe les doublons comme des succès. Son appelant est généralement un worker qui resoumet un travail entier après un redémarrage, et faire échouer un lot de 500 éléments parce qu’une clé était déjà en file réduirait à néant l’intérêt des clés d’idempotence. Le results[i].task renvoyé est la tâche existante, donc votre correspondance des tâches reste valable.

​
Rapprocher les résultats des soumissions

Deux repères indépendants, et il vous faut les deux :
​
integer
Correspond 1:1 par position à votre tableau d’entrée. Utilisez-le pour rapprocher la réponse du lot des tâches envoyées.
​
string
Renvoyée telle quelle. Utilisez-la pour rapprocher le webhook, qui arrive quelques minutes plus tard, dans le désordre, sans référence à votre tableau d’origine.
Si vous n’avez pas fourni d’idempotencyKey, le champ est omis de l’objet tâche au lieu d’être renvoyé à null. En interne, la tâche utilise son propre uuid comme clé, unique par construction, et donc jamais dédupliquée.

​
Durée de vie des clés

Les clés des tâches conservées de façon permanente restent réservées après la fin, l’échec et la fenêtre publique de polling de 24 heures. Un 404 au polling ne libère pas la clé. Utilisez la même clé pour les nouvelles tentatives réseau d’une soumission, et une nouvelle clé d’exécution (par exemple avec un suffixe :r1) pour une exécution distincte. Le format UUID n’est pas requis. Les enregistrements déjà déplacés vers l’historique hérité avant l’activation de la rétention permanente ne réservent pas de clé rétroactivement.