Passer au contenu principal
idempotencyKey est une chaîne facultative que vous définissez sur une soumission. Renvoyez la même clé et vous obtenez la tâche créée par la première soumission ; aucun nouveau travail n’est mis en file et aucun nouveau blocage de crédits n’est posé.
Sans clé, il n’y a pas de déduplication : chaque soumission crée une nouvelle tâche. Définissez une clé sur tout ce qu’une tâche cron ou un worker qui réessaie pourrait envoyer deux fois.
Construisez la clé à partir de l’unité de travail, pas de la tentative. Une clé comme "{jobId}:{promptId}:{engine}" est identique à chaque nouvelle tentative de ce travail.

Comment chaque endpoint traite une clé répétée

L’endpoint unitaire conserve une sémantique de création explicite : vous avez demandé de créer une tâche qui existe déjà, vous obtenez donc un conflit. L’erreur porte l’id de la tâche existante dans error.details.taskId, donc une soumission sans réponse peut être récupérée en interrogeant cet id.
Le lot de 500 tâches absorbe les doublons comme des succès : un worker peut renvoyer tout un job après un redémarrage sans que le lot échoue sur les éléments déjà soumis.

Grilles de localisation

L’idempotencyKey de la grille devient son id (un UUID est généré si vous l’omettez). La clé de tâche de chaque point est <grid id>:r<row>c<col>. Renvoyer la même grille sous cet id renvoie les points existants et n’admet que les points manquants. Envoyer une grille avec un autre centre, une autre taille ou un autre rayon sous le même id fait échouer les points dont les coordonnées diffèrent avec RESOURCE_ALREADY_EXISTS ; utilisez une nouvelle clé pour une nouvelle grille.

Portée et longueur

Les clés sont propres à votre compte : un autre compte peut utiliser la même chaîne sans collision avec la vôtre. Le format UUID n’est pas obligatoire.

Rapprocher les résultats des soumissions

Si vous n’avez pas envoyé de clé, idempotencyKey est omis de l’objet tâche, et non renvoyé à null.

Durée de vie de la clé

Une clé reste réservée pendant au moins 30 jours après la requête, y compris après la fin ou l’échec de la tâche et après la fermeture de la fenêtre 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 même soumission, et une nouvelle clé (par exemple avec un suffixe :r1) pour une exécution distincte du même travail.

Étapes suivantes

Lots et grilles

Les trois endpoints de soumission en masse côte à côte.

Erreurs

Tous les codes d’erreur de requête.