Guide d'intégration GloopAPI
Tâches asynchrones et idempotence
Récupérer les tâches et traiter les soumissions inconnues.
Une clé d'idempotence représente une opération métier de votre application. Avant l'envoi, enregistrez durablement le corps de la requête, l'identité de la Key et la clé de requête ; lors d'une répétition, conservez la même clé et les mêmes entrées normalisées. Modifier la requête avec la même clé provoque un conflit ; changer de clé crée une nouvelle opération facturable.
Devis et création
Pour les images et vidéos persistantes, consultez d'abord le catalogue des capacités, puis téléversez ou importez les entrées, obtenez un devis et confirmez explicitement la création. Les devis image et vidéo sont valables 60 secondes, et les devis d'outils 300 secondes ; le champ serveur expires_at indique l'échéance réelle. Un devis ne soumet rien au service et n'est pas facturé. Pour un nouvel appel non encore soumis, demandez un nouveau devis si le précédent expire ou si les entrées ou la configuration changent, puis vérifiez le nouveau coût avant la création ; si l'appel a déjà été soumis et que son résultat est inconnu, ne modifiez ni le devis ni la requête d'origine.
Un devis image ne verrouille pas les ressources d'entrée, qui sont revérifiées à la création. La vidéo n'accepte qu'un preset complet et des images hébergées correspondant au mode courant. Pour une vidéo persistante, envoyez explicitement retention: "persistent" ; une vidéo ordinaire conserve son propre contrat d'entrée par URL.
Décider en cas de soumission inconnue
Après réception d'un ID de tâche, interrogez uniquement la tâche d'origine ; en cas de délai dépassé sans ID, les images et vidéos persistantes disposent d'interfaces de récupération par clé de requête d'origine. Si un enregistrement existe, continuez à le surveiller ; un état unknown, submission_unknown, submission_state_unknown, billing_review ou en attente de vérification ne signifie ni échec ni remboursement et n'autorise pas une nouvelle génération avec une autre clé.
Pour un outil disposant d'un run_id, interrogez-le avec la Key d'origine ; si la réponse de création est perdue et qu'aucun run_id n'est disponible, répétez POST /v1/tool-runs avec la même API Key, le même Idempotency-Key et le corps complet d'origine, en conservant quote_id/version/input/max_cost_usd. Une exécution déjà acceptée restitue directement l'enregistrement d'origine, sans nouveau devis, sans dépendre des interrupteurs actuels et sans nouvelle soumission au service. L'historique est trié par created_at décroissant, puis id décroissant ; retransmettez next_cursor sans modification. La pagination n'est pas un instantané : actualisez la première page pour voir les nouveaux enregistrements précédant le curseur. Le clonage audio ne propose pas la même récupération par clé de requête ; conservez les preuves d'une soumission inconnue et vérifiez-la, sans utiliser la récupération des images.
Trois états indépendants
Évaluez séparément la réussite de la génération, le règlement comptable et la disponibilité du stockage. Une image peut réussir partiellement, un outil peut réussir sans que son utilisation finale soit confirmée, et une vidéo peut être générée mais ne pas être sauvegardée. Les workers poursuivent les tâches persistantes en arrière-plan ; fermer le navigateur ou arrêter l'interrogation côté client ne les annule pas.
L'annulation n'est qu'une demande : elle peut ne pas être prise en charge ou arriver trop tard ; continuez à vérifier l'état final et la facturation. Les opérations de stockage retry/archive-retry sauvegardent le résultat d'origine sans générer de nouveau contenu. La suppression d'une tâche exige un état terminal et une comptabilité définitive ; les preuves d'idempotence et de coût restent conservées après suppression.
Après récupération du résultat, vérifiez d'abord que le stockage est ready, puis obtenez une URL de téléchargement temporaire. L'expiration d'un lien temporaire du service peut rendre l'archivage irrécupérable ; ne masquez pas une erreur de sauvegarde par une nouvelle génération. Consultez Facturation et Gestion des erreurs.