# Comment éviter les tâches vidéo dupliquées après un timeout API ? > Évitez les doublons en donnant à chaque sortie voulue une clé d'opération stable, en enregistrant la requête avant l'envoi, en utilisant l'idempotence documentée du fournisseur lorsqu'elle existe et en conciliant les timeouts ambigus avant toute relance. Un timeout indique un résultat inconnu, pas un rejet. # Comment éviter les tâches vidéo dupliquées après un timeout API ? Un timeout d'envoi crée un résultat ambigu. La requête peut avoir échoué avant d'atteindre le service, avoir été rejetée après l'avoir atteint ou avoir créé une tâche distante dont la réponse n'est jamais revenue. Une relance immédiate peut transformer une seule vidéo voulue en deux générations payantes. La solution est une couche d'opérations idempotentes autour de l'API vidéo. Créez et persistez d'abord l'opération, attribuez-lui une clé stable, enregistrez chaque tentative et utilisez l'idempotence ou la recherche documentée. Si le résultat distant ne peut être prouvé, passez à un état inconnu explicite au lieu de supposer l'échec. ## Définissez un seul effet attendu La clé doit identifier ce que l'utilisateur a demandé, pas une tentative HTTP. Si chaque relance obtient une nouvelle clé, le fournisseur ne peut pas reconnaître le doublon. Une opération de catalogue peut être définie par : * ID produit ; * version du modèle créatif ; * empreinte du média source ; * version du prompt ; * locale ; * format ; * nom de variante. Créez une représentation canonique avec un ordre stable et des valeurs normalisées, puis calculez son hash. Stockez les dimensions lisibles et le hash. Une nouvelle génération intentionnelle doit créer une autre opération ou variante, même si le prompt est identique. Ne générez pas d'UUID aléatoire dans la boucle de relance. Créez la clé avant le premier envoi et réutilisez-la jusqu'à l'état terminal. ## Persistez avant d'envoyer La base locale doit connaître l'opération avant l'appel réseau. C'est le principe d'écriture anticipée appliqué aux effets d'une API. | Champ | Rôle | |---|---| | Clé d'opération | Empêche une intention locale dupliquée | | Hash de requête | Prouve les paramètres envoyés | | État | Distingue préparé, envoyé, inconnu et terminé | | Nombre de tentatives | Applique une politique limitée | | Fournisseur et modèle | Aide au routage et à la conciliation | | ID distant | Reprend l'interrogation sans renvoi | | Dernière erreur | Préserve le contexte de diagnostic | | Checksum de sortie | Détecte les actifs dupliqués ou modifiés | Ajoutez une contrainte unique sur la clé. Deux workers créant la même opération doivent converger vers un enregistrement. Prenez-le avec une mise à jour atomique ou un bail avant l'envoi. ## Utilisez l'idempotence uniquement comme documentée Certaines API acceptent une clé et renvoient le résultat de la première requête acceptée lors d'une répétition. C'est la voie la plus forte si la documentation couvre l'endpoint, la conservation, la comparaison des paramètres et les erreurs. Vérifiez : * si l'endpoint vidéo accepte la clé ; * combien de temps elle est mémorisée ; * si la même clé avec des paramètres différents est rejetée ; * si la relance renvoie l'ID distant original. Ne supposez pas qu'un header pris en charge pour les paiements ou le texte synchrone s'applique à une tâche vidéo asynchrone. Une forme compatible OpenAI ne rend pas automatiquement la création idempotente. ## Traitez les timeouts comme des résultats inconnus Utilisez des états fondés sur les preuves. | État | Preuve | Action suivante | |---|---|---| | `prepared` | Enregistrement local, envoi non commencé | Envoyer | | `sending` | Le worker a lancé l'appel | Attendre résultat ou timeout | | `accepted` | ID distant reçu | Interroger | | `unknown` | Timeout sans résultat confirmé | Concilier | | `failed` | Rejet ou échec terminal explicite | Appliquer la politique d'échec | | `complete` | Sortie stockée durablement | Renvoyer le résultat existant | La différence entre `unknown` et `failed` est essentielle. Une exception réseau prouve un problème de connexion client, pas nécessairement un échec du fournisseur. Ajoutez la clé locale aux métadonnées si une référence client existe. Elle fournit un identifiant stable pour une recherche ultérieure. ## Conciliez avant de relancer Un worker de conciliation examine l'opération inconnue. 1. Vérifiez si un ID distant a été sauvegardé avant la panne. 2. Recherchez par clé ou référence client si possible. 3. Parcourez une liste limitée par heure, modèle et empreinte. 4. Examinez les webhooks arrivés après le timeout. 5. Comparez les événements d'usage ou de facturation s'ils sont assez rapides. 6. Relancez seulement si l'absence de tâche est prouvée ou si l'idempotence le rend sûr. Une correspondance sur l'heure et le prompt seuls produit de faux positifs. Utilisez plusieurs attributs et envoyez les cas incertains en revue. Sans recherche ni idempotence, la politique peut être d'attendre, d'accepter le risque ou de demander une décision humaine. ## Séparez les relances de transport et de génération Les bibliothèques HTTP relancent parfois automatiquement les erreurs réseau. C'est utile pour les lectures, dangereux pour les envois avec effet. Désactivez les POST automatiques sans clé stable et prise en charge documentée. Utilisez deux compteurs : * tentatives de transport de la même opération protégée ; * tentatives de génération créant volontairement une sortie de remplacement. La première doit converger vers la même tâche distante. La seconde est une nouvelle tentative créative facturée, avec son propre ID relié à la tâche d'origine. ## Gérez les workers concurrents avec un bail Les timeouts ne sont pas la seule source de doublons. Deux workers peuvent prendre le même élément ou un worker lent peut continuer après expiration du bail. Prenez la tâche avec un bail atomique indiquant propriétaire, acquisition et expiration. Avant l'envoi, vérifiez la propriété et l'absence d'ID distant. Enregistrez l'ID par transaction ou mise à jour conditionnelle qui échoue si un autre worker a avancé. Utilisez des jetons de clôture si un ancien worker peut encore écrire. Chaque bail augmente une version et la base n'accepte que la plus récente. ## Faites converger webhooks et interrogations Une tâche vidéo est asynchrone, donc webhook et interrogation peuvent signaler la même transition. Les handlers doivent aussi être idempotents. Dédupliquez par ID d'événement et utilisez des mises à jour conditionnelles : `processing` ne doit pas faire reculer `complete`. Les téléchargements répétés écrivent sous une clé temporaire déterministe, vérifient le checksum et convergent vers un objet final. ```text recevoir la fin chercher l'opération par ID distant copier la sortie sous une clé déterministe vérifier média et checksum enregistrer l'URI durable marquer terminé si nécessaire ``` Si une étape tombe, le prochain handler reprend sans générer une autre vidéo. ## Enregistrez assez de preuves pour auditer Conservez les heures, le type de timeout, le hash, la clé, les headers, l'ID distant et la décision de relance. Masquez les identifiants secrets et données sensibles. | Indicateur | Ce qu'il révèle | |---|---| | Envois inconnus | Ambiguïté réseau ou fournisseur | | Conciliés sans relance | Doublons évités | | Relances protégées | Idempotence en cas de panne | | Tâches suspectées dupliquées | Risque financier résiduel | | Checksum de sortie dupliqué | Résultat identique ou répété | | Temps dans l'état inconnu | Vitesse de récupération | Si les résultats inconnus augmentent, cherchez la cause avant d'élever les limites. Une régression réseau combinée à des relances agressives multiplie les coûts. ## Encapsulez le comportement fournisseur Une application multimodèle doit exposer une interface interne avec des indicateurs de capacité. L'adaptateur contrôle schema, idempotence, recherche, mapping d'état et extraction de sortie. [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout) peut réduire l'intégration pour les équipes utilisant texte, image et vidéo via une plateforme compatible OpenAI. Vérifiez néanmoins le modèle et l'endpoint exacts. La compatibilité ne garantit pas une idempotence universelle des tâches asynchrones. Renvoyez un résultat normalisé : accepté avec ID, rejet explicite ou inconnu. Ne transformez pas une exception de transport en échec fournisseur. ## Testez volontairement les cas ambigus En préproduction, injectez des pannes avant l'envoi, après le départ des octets, après l'acceptation, après la réponse mais avant l'écriture en base et pendant le webhook. Avec idempotence, une opération doit produire au plus une tâche distante. Sans elle, elle doit entrer dans `unknown`, interrompre le renvoi automatique et fournir assez de preuves pour appliquer la politique. Testez aussi workers simultanés, baux expirés, webhooks retardés ou répétés, redémarrages et réutilisation d'une ancienne clé avec des paramètres modifiés. Ces tests coûtent moins cher qu'un doublon découvert sur la facture. ## Conclusion Donnez à chaque sortie une clé persistante et séparez l'opération de ses tentatives HTTP. Sauvegardez l'intention avant l'envoi, utilisez l'idempotence documentée et traitez le timeout comme un résultat inconnu à concilier. Avec des baux, des états conditionnels, des handlers idempotents et des journaux durables, la relance devient une récupération contrôlée plutôt qu'un achat répété accidentel. ## FAQ ### Un timeout HTTP signifie-t-il que l'API vidéo n'a pas créé de tâche ? Non. Le fournisseur peut avoir accepté la requête et créé la tâche sans que la réponse atteigne le client. Traitez le résultat comme inconnu jusqu'à sa conciliation. ### Que doit représenter une clé d'idempotence ? Un seul effet attendu, par exemple la combinaison produit, version de modèle, locale, format et variante. Réutilisez-la pour les relances de cette opération et créez-en une nouvelle pour une sortie réellement nouvelle. ### Une contrainte unique en base empêche-t-elle tous les doublons ? Elle empêche les opérations locales dupliquées, mais pas le fournisseur d'accepter deux requêtes. Combinez-la avec l'idempotence du fournisseur ou une procédure de conciliation. ### Le client doit-il relancer automatiquement tous les timeouts ? Non. La relance automatique est sûre seulement si la requête est idempotente ou si le résultat distant peut être déterminé. Sinon, placez la tâche dans un état inconnu et conciliez-la d'abord. ### Combien de temps conserver les enregistrements d'idempotence ? Au moins pendant les fenêtres de relance, de consultation fournisseur, de litige de facturation et d'audit. Adaptez la durée au comportement documenté et au risque métier. ### Une API compatible OpenAI garantit-elle la même idempotence pour tous les modèles vidéo ? Non. La compatibilité peut normaliser le transport, mais la création asynchrone et l'idempotence peuvent rester propres au modèle ou au fournisseur. Vérifiez la documentation actuelle.