# Come si evitano job video duplicati quando una richiesta API va in timeout? > Evita duplicati assegnando a ogni output una chiave operazione stabile, salvando la richiesta prima dell'invio, usando l'idempotenza documentata e riconciliando i timeout ambigui prima del retry. Un timeout significa esito sconosciuto, non rifiuto. # Come si evitano job video duplicati quando una richiesta API va in timeout? Un timeout di invio crea un esito ambiguo. La richiesta potrebbe essere fallita prima del servizio, essere arrivata e rifiutata, oppure aver creato un job remoto la cui risposta non è tornata al client. Un retry immediato può trasformare un clip previsto in due generazioni a pagamento. La soluzione è un livello operativo idempotente attorno all'API video. Crea e salva prima l'operazione prevista, assegnale una chiave stabile, registra ogni tentativo e usa l'idempotenza o la ricerca documentata dal provider. Se non puoi provare l'esito remoto, porta l'operazione in uno stato sconosciuto esplicito. ## Definisci un singolo effetto intenzionale La chiave deve identificare ciò che l'utente vuole creare, non un singolo tentativo HTTP. Se ogni retry riceve una chiave nuova, il provider non può riconoscere il duplicato. Un'operazione di catalogo può essere definita da: * ID prodotto; * versione del template creativo; * impronta dei media sorgente; * versione del prompt; * locale; * formato; * nome della variante. Crea una rappresentazione canonica con ordine stabile e valori normalizzati, quindi calcola l'hash. Conserva le dimensioni leggibili. Una nuova generazione intenzionale deve avere una nuova operazione o variante, anche se il prompt coincide. Non generare un UUID casuale dentro il ciclo di retry. Crea la chiave prima della prima richiesta e riutilizzala fino allo stato terminale. ## Salva prima di inviare Il database deve conoscere l'operazione prima della chiamata di rete. È il principio write-ahead applicato agli effetti delle API. | Campo | Scopo | |---|---| | Chiave operazione | Evita intenzioni locali duplicate | | Hash richiesta | Dimostra i parametri inviati | | Stato | Distingue preparato, inviato, sconosciuto e completo | | Conteggio tentativi | Applica una policy limitata | | Provider e modello | Supporta instradamento e riconciliazione | | ID remoto | Riprende il polling senza reinvio | | Ultimo errore | Conserva il contesto diagnostico | | Checksum output | Rileva asset duplicati o cambiati | Imposta un vincolo univoco. Due worker che creano la stessa operazione devono convergere su un record. Reclamalo con un aggiornamento atomico o una lease prima dell'invio. ## Usa l'idempotenza del provider solo come documentata Alcune API accettano una chiave e, se ripetuta, restituiscono il primo risultato accettato. È il percorso migliore quando la documentazione copre endpoint, durata, confronto parametri ed errori. Verifica: * se l'endpoint video supporta la chiave; * per quanto tempo viene ricordata; * se la stessa chiave con parametri diversi è rifiutata; * se i retry restituiscono l'ID originale. Non presumere che un header per pagamenti o testo sincrono valga per video asincroni. Una forma compatibile con OpenAI non rende automaticamente idempotente la creazione del job. ## Tratta i timeout come esiti sconosciuti | Stato | Prova | Prossima azione | |---|---|---| | `prepared` | Record locale, invio non iniziato | Invia | | `sending` | Il worker ha iniziato | Attendi risultato o timeout | | `accepted` | ID remoto ricevuto | Interroga | | `unknown` | Timeout senza conferma | Riconcilia | | `failed` | Rifiuto o errore finale esplicito | Applica la policy | | `complete` | Output salvato in modo durevole | Restituisci il risultato | La differenza tra `unknown` e `failed` è essenziale. Un'eccezione di rete descrive la connessione del client, non necessariamente il lavoro del provider. Se l'API consente metadati o un riferimento client, allega la chiave locale per avere un valore stabile da cercare. ## Riconcilia prima di ritentare Un worker di riconciliazione esamina l'operazione sconosciuta: 1. Controlla se il tentativo ha salvato un ID remoto. 2. Interroga per chiave o riferimento client. 3. Cerca in una lista limitata per ora, modello e impronta. 4. Esamina webhook arrivati dopo il timeout. 5. Confronta eventi di uso o fatturazione, se disponibili. 6. Ritenta solo quando è provato che il job non esiste o l'idempotenza rende sicuro il retry. Ora e prompt da soli possono produrre falsi positivi. Usa più attributi e invia le corrispondenze incerte alla revisione. Senza ricerca o garanzie, la policy può richiedere attesa, accettazione del possibile duplicato o decisione umana. ## Separa retry di trasporto e di generazione Le librerie HTTP possono ritentare automaticamente. È utile per letture sicure ma rischioso per invii con effetti. Disabilita retry POST generici se l'operazione non è protetta da una chiave stabile e documentata. Usa due contatori: * tentativi di trasporto della stessa operazione protetta; * tentativi di generazione di un sostituto dopo errore finale o rifiuto qualitativo. Il retry di trasporto deve convergere sullo stesso job remoto. Quello di generazione è un nuovo tentativo creativo fatturabile con una propria identità, collegato al job originale. ## Gestisci worker concorrenti con una lease I timeout non sono l'unica fonte di duplicati. Due worker possono prendere lo stesso elemento o uno lento può continuare dopo la scadenza del blocco. Reclama il lavoro con una lease atomica contenente proprietario, inizio e scadenza. Prima dell'invio verifica la proprietà e l'assenza di un job remoto già accettato. Salva l'ID remoto in una transazione o aggiornamento condizionale che fallisca se un altro worker è avanzato. Usa fencing token se un worker obsoleto può ancora scrivere. Ogni acquisizione incrementa una versione e il database accetta cambi solo dall'ultima. ## Fai convergere webhook e polling I job video sono asincroni, quindi polling e webhook possono segnalare la stessa transizione. Anche gli handler devono essere idempotenti. Deduplica per ID evento e usa aggiornamenti condizionali: `processing` non deve riportare indietro un job `complete`. Un doppio download scrive su una chiave temporanea deterministica, verifica il checksum e converge su un solo oggetto. ```text ricevi completamento trova operazione per ID remoto copia l'output su una chiave deterministica verifica media e checksum registra URI durevole marca completo se non lo è già ``` Se un passaggio si interrompe, il successivo può riprendere senza una nuova generazione. ## Registra prove sufficienti per l'audit Per ogni tentativo conserva timestamp, tipo di timeout, hash, chiave idempotente, header di risposta, ID remoto e decisione di retry. Oscura credenziali e dati sensibili. | Metrica | Che cosa rivela | |---|---| | Invii sconosciuti | Ambiguità di rete o provider | | Riconciliati senza retry | Duplicati evitati | | Retry protetti | Comportamento idempotente sotto errore | | Sospetti duplicati | Rischio finanziario residuo | | Checksum duplicato | Risultato uguale o ripetuto | | Tempo in unknown | Velocità di recupero | Avvisa su una crescita degli esiti ignoti prima di aumentare i retry. Una regressione di rete con retry aggressivi moltiplica rapidamente i costi. ## Nascondi il comportamento del provider dietro un adapter Un'app multi-modello dovrebbe avere un'interfaccia interna e flag di capacità. L'adapter gestisce schema, idempotenza, ricerca, mapping degli stati ed estrazione dell'output. [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout) può ridurre il lavoro per team che usano testo, immagini e video tramite una piattaforma compatibile con OpenAI. Verifica comunque il comportamento del modello e endpoint esatti: la compatibilità non è una promessa universale di idempotenza asincrona. Restituisci un risultato normalizzato: accettato con ID, rifiuto esplicito o sconosciuto. Non trasformare le eccezioni di trasporto in errori del provider. ## Testa deliberatamente i casi ambigui Il percorso positivo non prova la sicurezza. In staging inserisci errori prima dell'invio, dopo l'uscita dei byte, dopo l'accettazione, dopo la risposta ma prima del database e durante i webhook. Con idempotenza, un'operazione deve produrre al massimo un job remoto. Senza, deve entrare in `unknown`, sospendere il reinvio automatico e mostrare prove sufficienti. Testa anche worker simultanei, lease scadute, webhook tardivi e ripetuti, riavvii e riuso di una chiave con parametri cambiati. Costa meno che scoprire duplicati nella fattura. ## In sintesi Evita duplicati dando a ogni output una chiave persistente e separando l'operazione dai tentativi HTTP. Salva l'intenzione prima dell'invio, usa l'idempotenza documentata e considera il timeout un esito sconosciuto da riconciliare. Lease, cambi condizionali, completamento idempotente e log durevoli trasformano i retry in recupero controllato invece che in acquisti duplicati. ## FAQ ### Un timeout HTTP significa che l'API video non ha creato un job? No. Il provider potrebbe aver accettato la richiesta e creato il job anche se il client non ha ricevuto la risposta. Considera l'esito sconosciuto finché non viene riconciliato. ### Che cosa deve rappresentare una chiave di idempotenza? Un singolo effetto intenzionale, per esempio prodotto, versione template, locale, formato e variante. Riutilizzala per i retry della stessa operazione e creane una nuova per un output realmente nuovo. ### Un vincolo univoco nel database evita tutti i duplicati? Evita operazioni locali duplicate, ma non impedisce da solo al provider di accettare due richieste. Abbinalo all'idempotenza del provider o alla riconciliazione. ### Il client dovrebbe ritentare automaticamente ogni timeout? No. I retry automatici sono sicuri solo se la richiesta è idempotente o l'esito del provider può essere determinato. Altrimenti porta il job in stato sconosciuto e riconcilialo. ### Quanto a lungo vanno conservati i record di idempotenza? Almeno per la finestra di retry, ricerca del provider, contestazione della fattura e audit operativo. Allinea il periodo al comportamento documentato e al rischio. ### Un'API compatibile con OpenAI garantisce la stessa idempotenza per tutti i modelli video? No. La compatibilità può normalizzare il trasporto, ma creazione asincrona e idempotenza possono restare specifiche del modello o provider. Verifica la documentazione corrente.