Guida all'integrazione GloopAPI
Attività asincrone e idempotenza
Recupera le attività e gestisci gli invii sconosciuti.
Una chiave di idempotenza rappresenta un'operazione aziendale dell'applicazione. Prima dell'invio, conserva in modo persistente il corpo della richiesta, l'identità della Key e la chiave di richiesta; per la ripetizione usa la stessa chiave e gli stessi input normalizzati. Modificare la richiesta mantenendo la chiave provoca un conflitto; cambiare chiave crea una nuova operazione a pagamento.
Preventivo e creazione
Per immagini e video persistenti, consulta prima il catalogo delle funzionalità, poi carica o importa gli input, ottieni un preventivo e conferma esplicitamente la creazione. I preventivi di immagini e video durano 60 secondi, quelli degli strumenti 300 secondi; il valore server expires_at indica la scadenza effettiva. Il preventivo non invia nulla al servizio e non comporta addebiti. Per una nuova chiamata non ancora inviata, richiedi un nuovo preventivo se quello precedente è scaduto o se input o configurazione sono cambiati, e controlla il nuovo costo prima della creazione. Se la chiamata è già stata inviata ma l'esito è sconosciuto, non modificare preventivo e richiesta originali.
Il preventivo delle immagini non blocca le risorse di input, che vengono ricontrollate alla creazione. I video accettano soltanto un preset completo e fotogrammi ospitati compatibili con la modalità corrente. Per i video persistenti invia esplicitamente retention: "persistent"; i video ordinari continuano a seguire il proprio contratto per gli input URL.
Decisioni per invii dall'esito sconosciuto
Dopo aver ricevuto l'ID dell'attività, interroga soltanto quella originale. In caso di timeout senza ID, immagini e video persistenti possono essere recuperati tramite gli endpoint che accettano la chiave di richiesta originale. Se esiste un record, continua a osservarlo. Gli stati unknown, submission_unknown, submission_state_unknown, billing_review o in attesa di verifica non indicano un errore o un rimborso e non autorizzano una nuova generazione con un'altra chiave.
Per gli strumenti con run_id, interroga l'esecuzione usando la Key originale. Se la risposta di creazione va persa e manca run_id, ripeti POST /v1/tool-runs con API Key, Idempotency-Key e corpo completo originali, mantenendo quote_id/version/input/max_cost_usd. Un'esecuzione già accettata recupera direttamente il record originale, senza dipendere da un nuovo preventivo o dalle abilitazioni correnti e senza un nuovo invio al servizio. La cronologia è ordinata per created_at decrescente e poi id decrescente; ritrasmetti next_cursor senza modificarlo. La paginazione non è un'istantanea: aggiorna la prima pagina per vedere i nuovi record che precedono il cursore. La clonazione audio non offre lo stesso recupero tramite chiave di richiesta; conserva le prove di un invio sconosciuto e verificalo, senza applicare il percorso di recupero delle immagini.
Tre stati indipendenti
Valuta separatamente il successo della generazione, la chiusura contabile e la disponibilità dello storage. Le immagini possono riuscire parzialmente, gli strumenti possono riuscire prima della conferma dell'utilizzo finale, e i video possono essere generati ma non salvati. I worker continuano le attività persistenti in background; chiudere il browser o interrompere le interrogazioni del client non le annulla.
L'annullamento è soltanto una richiesta: potrebbe non essere supportato o arrivare troppo tardi. Continua a osservare lo stato finale e la contabilità. Le operazioni storage retry/archive-retry salvano soltanto il risultato originale, senza generare nuovi contenuti. La cancellazione di un'attività richiede uno stato terminale e una contabilità definitiva; le prove di idempotenza e costo restano conservate dopo la cancellazione.
Dopo aver recuperato il risultato, controlla prima che lo storage sia ready, poi ottieni un URL temporaneo di download. La scadenza del collegamento temporaneo del servizio può rendere impossibile l'archiviazione; non nascondere un errore di salvataggio generando un nuovo risultato. Consulta Fatturazione e Gestione degli errori.