Zum Hauptinhalt springen

​
Überblick

Diese Seite führt von Angebot und Kostenreservierung über asynchrone Ausführung zur Abrechnung und zum Artefaktabruf. Verfolgen Sie lange Aufträge über ihre ID, statt eine HTTP-Verbindung offen zu halten.

​
Ausführung und Abrechnung verstehen

POST /tools/quote liefert Preisversion, Mindestgebühr und maximalen Reservierungsbetrag für die Eingabe. Angebote sind kostenlos: Sie rufen keine externen Dienste auf und reservieren kein Guthaben. Ergänzen Sie dieselben tool und arguments aus dem Angebot um diese Felder:
  • priceVersion — Preisversion aus dem Angebot
  • maximumChargeMicros — Maximaler Reservierungsbetrag aus dem Angebot
Bei geänderten Preisen oder zu niedrigem Limit wird die Anfrage vor Verarbeitungsbeginn abgelehnt. Holen Sie ein neues Angebot ein und prüfen Sie es erneut.

​
Beträge reservieren und abrechnen

Bei Annahme wird der Höchstbetrag vorübergehend vom USD-Prepaid-Guthaben reserviert. Nach Abschluss werden tatsächliche Kosten abgerechnet und ungenutzte Beträge freigegeben. Bei Fehlern oder Abbruch werden bereits entstandene externe Kosten abgerechnet. Eine automatische Belastung über den reservierten Höchstbetrag hinaus erfolgt nicht.

​
Ausführungsstatus verfolgen

Bei Annahme erhalten Sie HTTP 202 und eine Ausführungs-ID. Beachten Sie Retry-After: 5 und fragen Sie dieselbe ID frühestens alle fünf Sekunden ab.

​
Doppelte Ausführungen verhindern

Ein Idempotenzschlüssel verhindert, dass versehentlich mehrfach gesendete Anfragen separate Ausführungen erzeugen. Kostenpflichtige Aufrufe von POST /tools/{tool} benötigen den Header Idempotency-Key. Schlüssel bestehen aus 8–128 Zeichen: Buchstaben, Ziffern, ., _, : oder -. Erzeugen Sie einen pro logischer Anfrage und speichern Sie ihn mit der Ausführungs-ID.
  • Derselbe API-Schlüssel, Inhalt und Idempotenzschlüssel liefern dieselbe Ausführung.
  • Geänderter Inhalt oder API-Schlüssel bei gleichem Idempotenzschlüssel ergibt HTTP 409.
  • Nach Verbindungsabbruch mit unverändertem Inhalt und Idempotenzschlüssel erneut senden.
  • Eine erneute Anfrage mit Status needs_review und neuem Idempotenzschlüssel erzeugt einen weiteren kostenpflichtigen Auftrag.
Eine fehlende Antwort beweist nicht, dass der Auftrag abgelehnt wurde. Erstellen Sie bei unbekanntem Ergebnis keinen neuen Idempotenzschlüssel.

​
Ausführung abbrechen

POST /tools/executions/{id}/cancel fordert den Stopp noch nicht begonnener Arbeit an. Dies darf der erstellende Schlüssel oder ein Projekt-ADMIN anfordern. Bereits begonnene externe Verarbeitung und deren Kosten lassen sich möglicherweise nicht rückgängig machen. Prüfen Sie cancelRequested sowie den endgültigen status und chargedMicros.

​
Artefakte abrufen

Generierte Bilder, Audio- und Videodateien erscheinen unter output.artifacts mit Datei-ID, Format, Größe, Hash und Ablaufdatum. Dateiinhalte und permanente URLs sind nicht im Ausführungsergebnis enthalten. GET /tools/executions/{id}/artifacts/{artifactId}/download liefert eine bis zu fünf Minuten gültige Download-URL. Gespeicherte Dateien laufen nach 30 Tagen ab. Auch befristete URLs ermöglichen Zugriff auf private Daten. Protokollieren oder veröffentlichen Sie sie nicht und hängen Sie keinen Developer-Platform-API-Schlüssel an.

​
Weiterführende Seiten

Erste Ausführung und Endpunkte erläutern diese Seiten.