Dokumentation

API-Referenz

Persistente Bildaufgabe erstellen

POST/v1/image-tasks

Gültige quote_id und Idempotency-Key müssen übereinstimmen. Einmalige Hintergrundausführung mit Abrechnung/Archivierung; bei unknown oder billing_review nicht blind erneut senden. Anfragen maximal 128 KiB; unbekannte Felder werden abgelehnt.

Vom Kostenvoranschlag zum Ergebnis

Bereiten Sie zunächst verfügbare Eingaben vor, holen Sie einen Kostenvoranschlag ein und senden Sie nach ausdrücklicher Bestätigung quote_id zusammen mit den ursprünglichen Parametern. Der Kostenvoranschlag sperrt keine Ressourcen. Löscht der Benutzer eine Ressource vor der Bestätigung, kann die Erstellung scheitern; korrigieren Sie dann die Eingaben und holen Sie einen neuen Kostenvoranschlag ein.

Die Anwendung sollte sowohl den geschäftlichen Anfrageschlüssel als auch die Aufgaben-ID speichern. Stellen Sie nach einem Client-Verbindungsabbruch anhand des ursprünglichen Schlüssels wieder her, statt bei unbekanntem Status neu zu generieren. Prüfen Sie auch bei Teilerfolg jedes Ergebnis und dessen Speicherstatus vor dem Download. Siehe Asynchrone Aufgaben und Idempotenz.

Authentifizierung und Berechtigungen

Verwenden Sie Ihren aktuellen GloopAPI-Schlüssel. Verfügbare Modelle, Funktionen und Berechtigungen hängen von seinem Katalog und der Endpunktdokumentation ab.

Authorization: Bearer $GLOOP_API_KEY

Authentifizierungsschemata: BearerAuth

Anfrage

Anfrageheader

  • Idempotency-KeystringErforderlich

    Ursprüngliche Anfrageabsicht mit demselben Schlüssel aufbewahren. Nach einer Netzwerkunterbrechung zuerst die Wiederherstellung abfragen; bei unbekanntem Status nicht blind erneut senden.

    Mindestlänge
    1
    Maximale Länge
    191

Anfragekörper · application/json

Typ
object
Pflichtfelder
modelpromptsize
Zusätzliche Eigenschaften
false

Anfragekörper erforderlich

  • modelstringErforderlich

    Öffentliche Modell-ID aus dem Katalog des aktuellen Schlüssels.

    Maximale Länge
    191
  • promptstringErforderlich

    Nicht leer, maximal 32000 UTF-8-Bytes. OpenAPI maxLength zählt Zeichen, daher wird keine künstliche Zeichengrenze angegeben.

  • sizestringErforderlich

    Größenwert aus dem ausgewählten image-models-Eintrag; Funktionen und Größen werden je Modell geprüft.

  • nintegerOptional

    Ausgelassen oder 0 wird zu 1 normalisiert. Tatsächliches Maximum ist max_n aus image-models; das globale Maximum ist keine Modellfähigkeit.

    Standardwert
    1
    Minimum
    1
    Maximum
    6
  • referencesarrayOptional

    Pro Element nur eines von file_id, asset_id oder url wählen; tatsächliche Anzahl gemäß max_references.

    Maximale Elementanzahl
    14
    Unterfelder von references (1)
    • []objectOptional
      Unterfelder von [] (3)
      • file_idstringOptional

        Öffentliche ID einer verwalteten Datei desselben Kontos und Schlüssels.

      • asset_idstringOptional

        ID eines hochgeladenen Objekts desselben Kontos und Schlüssels.

      • urlstringOptional

        Öffentliche HTTPS-URL ohne userinfo oder fragment; SSRF-geprüft.

        Format
        "uri"
      oneOf-Zweig 1

      In diesem Zweig erforderlich: file_id

      oneOf-Zweig 2

      In diesem Zweig erforderlich: asset_id

      oneOf-Zweig 3

      In diesem Zweig erforderlich: url

  • source_task_idstringOptional

    Optionale Quellaufgabe desselben Schlüssels, nur zur Herkunftsverfolgung; ersetzt references nicht.

    Maximale Länge
    64
  • quote_idstringOptional

    Bei Erstellung gültiges, zur Anfrage passendes Angebot erforderlich; in Angebotsanfragen ignoriert.

Antworten und Fehler

HTTP 202

Persistente Bildaufgabe erfolgreich erstellt

application/json

Typ
object
Pflichtfelder
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringErforderlich

    Öffentliche Modell-ID aus dem Katalog des aktuellen Schlüssels.

  • promptstringErforderlich

    Generierungsprompt.

  • sizestringErforderlich

    Größenwert aus dem ausgewählten image-models-Eintrag; Funktionen und Größen werden je Modell geprüft.

  • nintegerErforderlich

    Angeforderte Anzahl der Ausgabebilder, weiterhin durch das Modellmaximum begrenzt.

  • referencesarrayErforderlich

    Liste der Referenzbilder für die Generierung.

    Unterfelder von references (1)
    • []objectOptional
      Unterfelder von [] (3)
      • file_idstringOptional

        Öffentliche ID einer verwalteten Datei desselben Kontos und Schlüssels.

      • asset_idstringOptional

        ID eines hochgeladenen Objekts desselben Kontos und Schlüssels.

      • urlstringOptional

        Öffentliche HTTPS-URL ohne userinfo oder fragment; SSRF-geprüft.

        Format
        "uri"
      oneOf-Zweig 1

      In diesem Zweig erforderlich: file_id

      oneOf-Zweig 2

      In diesem Zweig erforderlich: asset_id

      oneOf-Zweig 3

      In diesem Zweig erforderlich: url

  • source_task_idstringOptional

    Öffentliche Quellaufgaben-ID, nur zur Herkunftsverfolgung.

  • quote_idstringOptional

    Öffentliche Kostenvoranschlags-ID; muss beim Erstellen zur Preis- und Anfragebindung passen.

  • idstringErforderlich

    Öffentliche Kennung dieses Objekts für den zugehörigen Detailpfad.

  • statusstringErforderlich

    unknown wird nicht automatisch wiederholt; Vorabbuchung kann pending bleiben.

    Aufzählung
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerErforderlich

    Erstellungszeit in Unix-Sekunden.

  • updated_atintegerErforderlich

    Letzte Aktualisierung in Unix-Sekunden.

  • reserved_quotaintegerErforderlich

    Reservierung in Plattform-quota-Einheiten, nicht in Dollar.

  • final_quotaintegerErforderlich

    Endkosten in Plattform-quota-Einheiten; null bedeutet noch unbestimmt.

  • billing_statusstringErforderlich

    Reservierungs-/Abrechnungs-/Erstattungsstatus; getrennt von Aufgaben- und Archivierungsstatus prüfen.

  • error_codestringOptional

    Öffentlicher Fehlercode für Fallunterscheidungen.

  • error_messagestringOptional

    Nutzerbeschreibung nach öffentlicher Fehlerklassifizierung.

  • resultsarrayErforderlich

    Generierte Ausgabeelemente; jedes hat einen unabhängigen Archivierungsstatus.

    Unterfelder von results (1)
    • []objectOptional
      Unterfelder von [] (7)
      • file_idstringOptional

        Öffentliche ID einer verwalteten Datei desselben Kontos und Schlüssels.

      • storage_statusstringOptional

        Dateiarchivierungsstatus; verwaltete Downloads sind erst nach ready garantiert verfügbar.

      • storage_errorstringOptional

        Öffentliche Kategorie eines Dateiarchivierungsfehlers.

      • expires_atintegerOptional

        Ablauf in Unix-Sekunden; 0 bedeutet keine feste Frist.

      • urlstringOptional

        Zugriffs-URL für Ergebnis oder Referenz; signierte URLs gelten nur kurzzeitig.

      • b64_jsonstringOptional

        Base64-Zeichenfolge des Bildes; nicht als URL aufrufen.

      • revised_promptstringOptional

        Vom Dienst zurückgegebener überarbeiteter Prompt, sofern vorhanden.

HTTP 400

Ungültige Anfragefelder oder Parameter.

application/json

Typ
object
Pflichtfelder
error

HTTP 401

Key fehlt, ist ungültig, abgelaufen oder widerrufen.

application/json

Typ
object
Pflichtfelder
error

HTTP 403

Unzureichende IP-, Konto-, Modell- oder Tool-Berechtigungen.

application/json

Typ
object
Pflichtfelder
error

HTTP 404

Objekt/Funktion nicht verfügbar oder Funktionsschalter deaktiviert.

application/json

Typ
object
Pflichtfelder
error

HTTP 409

Idempotenz-/Kostenvoranschlagskonflikt, Objekt nicht bereit oder noch referenziert.

application/json

Typ
object
Pflichtfelder
error

HTTP 429

Anfrage-/Warteschlangenlimit.

application/json

Typ
object
Pflichtfelder
error

HTTP 500

Interner Authentifizierungs- oder Datenspeicherungsfehler.

application/json

Typ
object
Pflichtfelder
error

HTTP 503

Dienst, Preisberechnung oder Speicherung nicht verfügbar.

application/json

Typ
object
Pflichtfelder
error
Bereit zum Entwickeln? Öffnen Sie Konsole um einen API-Schlüssel zu erstellen, oder durchsuchen Sie Funktionen.