GloopAPI-Integrationsleitfaden
Asynchrone Aufgaben und Idempotenz
Aufgaben wiederherstellen und unbekannte Übermittlungen behandeln.
Ein Idempotenzschlüssel steht für einen Geschäftsvorgang Ihrer Anwendung. Speichern Sie vor dem Senden den Anfragekörper, die Key-Identität und den Anfrageschlüssel dauerhaft; verwenden Sie bei einer Wiederholung denselben Schlüssel und dieselben normalisierten Eingaben. Eine geänderte Anfrage mit demselben Schlüssel führt zu einem Konflikt; ein anderer Schlüssel erzeugt einen neuen kostenpflichtigen Vorgang.
Kostenvoranschlag und Erstellung
Lesen Sie für persistente Bilder und Videos zuerst den Funktionskatalog, laden oder importieren Sie dann die Eingaben, holen Sie einen Kostenvoranschlag ein und bestätigen Sie die Erstellung ausdrücklich. Bild- und Videokostenvoranschläge gelten 60 Sekunden, Tool-Kostenvoranschläge 300 Sekunden; das serverseitige expires_at ist die tatsächliche Frist. Ein Kostenvoranschlag übermittelt nichts an den Dienst und verursacht keine Gebühr. Bei einem noch nicht eingereichten neuen Aufruf müssen Sie nach Ablauf oder Änderungen an Eingaben oder Konfiguration einen neuen Kostenvoranschlag einholen und die neuen Kosten vor der Erstellung prüfen. Wurde der Aufruf bereits eingereicht und ist das Ergebnis unbekannt, dürfen ursprünglicher Kostenvoranschlag und Anfrage nicht geändert werden.
Ein Bildkostenvoranschlag sperrt die Eingaberessourcen nicht; sie werden bei der Erstellung erneut geprüft. Videos erlauben nur ein vollständiges preset und gehostete Frames, die zum aktuellen Modus passen. Senden Sie für persistente Videos ausdrücklich retention: "persistent"; normale Videos folgen weiterhin ihrem eigenen Vertrag für URL-Eingaben.
Entscheidungen bei unbekannter Übermittlung
Sobald eine Aufgaben-ID vorliegt, fragen Sie nur die ursprüngliche Aufgabe ab. Bei einem Timeout ohne ID können persistente Bilder und Videos über die Wiederherstellungsendpunkte mit dem ursprünglichen Anfrageschlüssel gesucht werden. Existiert ein ursprünglicher Datensatz, beobachten Sie ihn weiter. unknown, submission_unknown, submission_state_unknown, billing_review oder ein Prüfstatus bedeuten weder Fehler noch Erstattung und erlauben keine neue Generierung mit einem anderen Schlüssel.
Liegt für ein Tool eine run_id vor, fragen Sie sie mit der ursprünglichen Key ab. Geht die Erstellungsantwort ohne run_id verloren, wiederholen Sie POST /v1/tool-runs mit der ursprünglichen API Key, dem ursprünglichen Idempotency-Key und dem vollständigen ursprünglichen Anfragekörper; behalten Sie quote_id/version/input/max_cost_usd bei. Bereits angenommene Ausführungen stellen direkt den ursprünglichen Datensatz wieder her, unabhängig von einem neuen Kostenvoranschlag oder aktuellen Schaltern und ohne erneute Übermittlung an den Dienst. Der Verlauf ist nach created_at und anschließend id absteigend sortiert; geben Sie next_cursor unverändert zurück. Die Seitennavigation ist kein Schnappschuss: Aktualisieren Sie die erste Seite, um neue Datensätze vor dem Cursor zu sehen. Audioklonen bietet nicht dieselbe Wiederherstellung nach Anfrageschlüssel. Bewahren Sie bei unbekannter Übermittlung die Nachweise auf und prüfen Sie den Vorgang, statt den Bild-Wiederherstellungspfad zu verwenden.
Drei unabhängige Zustände
Bewerten Sie erfolgreiche Generierung, abgeschlossene Abrechnung und bereiten Speicher getrennt. Bilder können teilweise erfolgreich sein, Tools können vor Bestätigung der endgültigen Nutzung erfolgreich sein, und Videos können erfolgreich erzeugt, aber nicht gespeichert werden. Hintergrund-Worker führen persistente Aufgaben weiter aus; das Schließen des Browsers oder Beenden der clientseitigen Abfragen ist kein Abbruch.
Ein Abbruch ist nur eine Anfrage: Er wird möglicherweise nicht unterstützt oder kommt zu spät. Beobachten Sie Endzustand und Abrechnung weiter. Die Speicheraktionen retry/archive-retry speichern nur das ursprüngliche Ergebnis und erzeugen keinen neuen Inhalt. Das Löschen einer Aufgabe erfordert einen Endzustand und endgültige Abrechnung; Idempotenz- und Kostennachweise bleiben danach erhalten.
Prüfen Sie nach Abruf des Ergebnisses zuerst, ob der Speicher ready ist, und holen Sie dann eine kurzlebige Download-URL. Läuft der temporäre Dienstlink ab, kann eine Archivierung unwiederbringlich scheitern; verdecken Sie Speicherfehler der ursprünglichen Aufgabe nicht durch neue Generierung. Siehe Abrechnung und Fehlerbehandlung.