Skip to main content

Schnellstart

Der native Bildendpunkt arbeitet standardmäßig synchron. Setzen Sie den booleschen Wert async auf true, um eine Hintergrundaufgabe zu erstellen. Das Beispiel verwendet qwen-image-2.0.

Wie findet man asynchrone Medienmodelle und ruft ihre Schemas ab?

Die Ermittlung erfolgt in zwei Schritten. Rufen Sie zuerst Text-zu-Bild- oder Text-zu-Video-Modelle mit Unterstützung für die asynchronen APIs aus dem öffentlichen Modellkatalog ab. Verwenden Sie anschließend die model_id, um das Anfrageschema der Endpunkte des Modells abzurufen.

Modelle mit Unterstützung für die asynchronen APIs auflisten

Der Modellkatalog verwendet dieselbe Datenquelle wie Playground. Nutzen Sie type=image_generation für Text-zu-Bild-Modelle und type=video für Text-zu-Video-Modelle. Mit schema_checked=true enthält die Liste nur Modelle mit veröffentlichtem und geprüftem Anfrageschema.
Beide Anfragen verwenden denselben Endpunkt. Der Filter type akzeptiert derzeit einen Wert. Fragen Sie daher jeden Modelltyp separat ab. Die Antwort hat die Form {success, message, data}. Für asynchrone Medienintegrationen sind die folgenden Felder in data relevant.

Anfrageschema eines einzelnen Modells abrufen

Unterstützte Felder, Aufzählungswerte und Wertebereiche können je nach Modell variieren. Rufen Sie vor einer Bild- oder Videoanfrage über den folgenden öffentlichen Endpunkt die verfügbaren Endpunkte und Anfrage-JSON-Schemas des gewählten Modells ab.
Die Antwort enthält für modality den Wert image oder video. Jeder Eintrag im Array endpoints beschreibt ein verfügbares Aufrufprotokoll. Ein Modell kann sowohl /ai/v1-Endpunkte als auch OpenAI-kompatible /v1-Endpunkte zurückgeben. OpenAI-kompatible Endpunkte unterstützen die neuesten Modelle möglicherweise noch nicht. Verwenden Sie daher bevorzugt die /ai/v1-Endpunkte. Wählen Sie für die asynchronen Aufgaben-APIs den Eintrag mit dem path /ai/v1/images/generations oder /ai/v1/videos aus und verwenden Sie dessen request.schema. Verlassen Sie sich nicht auf die Position eines Eintrags im Array endpoints. Die folgenden Befehle extrahieren das Anfrageschema für die beiden asynchronen Aufgabenendpunkte.
Der Endpunkt gibt 404 model_not_found zurück, wenn das Modell nicht existiert oder keine auffindbaren Endpunkte besitzt. Wenn die Endpunktdaten vorübergehend nicht verfügbar sind, wird 500 endpoints_unavailable zurückgegeben.

Wie erstellt man Bildaufgaben?

Synchrone Bilder

Wenn Sie async weglassen oder auf false setzen, wartet der Endpunkt auf den Abschluss der Generierung und gibt anschließend das Aufgabenobjekt zurück:
Auch synchrone Bildaufgaben werden als Aufgabendatensatz gespeichert. Wird die Clientverbindung unterbrochen oder geht die Erstellungsantwort verloren, können Sie die entsprechende Aufgabe über GET /ai/v1/images suchen.

Asynchrone Bilder

Wenn Sie async auf den booleschen Wert true setzen, gibt der Endpunkt sofort ein Aufgabenobjekt zurück und die Generierung wird im Hintergrund fortgesetzt:
Fragen Sie asynchrone Bildaufgaben mit GET /ai/v1/images/{id} ab. Nach dem Abschluss können Sie die content_url jedes output-Eintrags direkt anfordern. Diese URL enthält bereits die result_id des jeweiligen Bildes.
async muss in Bildanfragen ein boolescher Wert sein. webhook_url und webhook_events_filter können nur zusammen mit async: true verwendet werden.

Standardfelder für Bilder


Objekt einer Medienaufgabe

Die dedizierten Endpunkte für Bilder und Videos geben folgende Struktur zurück:
Einträge in output für Medien:

Statusbeschreibung

Der Client kann alle 15 Sekunden abfragen, bis der Status completed, failed oder cancelled lautet. Die 15 Sekunden sind eine Empfehlung für das clientseitige Polling und keine Einschränkung des Serverprotokolls.

Wie fragt man Medienaufgaben ab?

Mediendetails abfragen

Die Detailendpunkte für Medien können einen aktualisierten Aufgabenstatus zurückgeben. Verwenden Sie zum Polling von Medien daher den jeweiligen Detailendpunkt für Bilder oder Videos.

Medienliste abfragen

Falls die Erstellungsantwort verloren geht, können Sie die Aufgaben-ID über die entsprechende Medienliste wiederfinden:
Medienlisten geben eine Momentaufnahme zum Abfragezeitpunkt zurück und aktualisieren den Aufgabenstatus nicht aktiv.

Wie verwendet man einheitliche Aufgabenendpunkte?

Die einheitlichen Aufgabenendpunkte unterstützen folgende Filter:
Details einer einheitlichen Aufgabe:
Einheitlicher output-Eintrag einer Medienaufgabe:
Fordern Sie bei einem einzelnen Artefakt direkt /ai/v1/tasks/{id}/content an. Bei Aufgaben mit mehreren Artefakten müssen Sie /ai/v1/tasks/{id}/content/{result_id} anfordern. Ohne Ergebnis-ID wird 400 result_id_required zurückgegeben.
Die einheitlichen Endpunkte für Aufgabenlisten, Details und Inhalte sind nach dem Bearer Token isoliert, mit dem die Aufgabe erstellt wurde. Andere API Keys desselben Kontos können die Aufgabe nicht lesen.

Medienergebnisse herunterladen

Bilder herunterladen

Fordern Sie nach Abschluss der Bildaufgabe die output[].content_url jedes Eintrags im Medienaufgabenobjekt an:
Der Medienpfad zum Herunterladen eines Bildes lautet /ai/v1/images/{id}/content/{result_id}. Das Medienaufgabenobjekt veröffentlicht result_id nicht separat. Der Client kann direkt content_url verwenden. Wenn b64_json nicht leer ist, können Sie dieses Feld direkt Base64-decodieren.

Webhooks verwenden

Asynchrone Bilder und Videos unterstützen Webhooks auf Aufgabenebene:
webhook_url darf höchstens 512 Zeichen lang sein und nicht auf den lokalen Rechner, ein privates Netzwerk oder eine andere eingeschränkte Adresse verweisen. Wenn Sie webhook_events_filter weglassen, sendet die Plattform completed, failed und cancelled. Bei expliziter Angabe darf das Array weder leer sein noch Duplikate enthalten und muss zusammen mit webhook_url verwendet werden. Wenn die Anfrage keine webhook_url enthält, versuchen asynchrone Bilder und Videos, die im Konto konfigurierte Standard-Callback-URL zu verwenden. Eine ungültige Standardadresse des Kontos wird ignoriert und verhindert die Erstellung der Aufgabe nicht.

Callback-Anfrage

results ist nur vorhanden, wenn das Ergebnis archiviert wurde. Für den Download ist weiterhin ein Bearer Token erforderlich.

Wiederholungsversuche und Deduplizierung

Die Plattform stellt mindestens einmal zu. Dasselbe Ereignis kann daher mehrfach eintreffen:
  • HTTP 2xx kennzeichnet einen erfolgreichen Empfang.
  • HTTP 5xx, Netzwerkfehler oder Zeitüberschreitungen lösen einen erneuten Versuch aus.
  • Bei HTTP 3xx und 4xx erfolgt kein erneuter Versuch.
  • Es erfolgen höchstens 6 Zustellversuche mit Abständen von 1, 4, 16, 64 und 256 Sekunden.
Der Empfänger sollte event_id speichern und beim erneuten Empfang desselben Ereignisses direkt 2xx zurückgeben.
Webhooks auf Aufgabenebene besitzen keinen eigenen Signaturschlüssel. Wenn Sie eine Signaturprüfung benötigen, konfigurieren Sie ein Webhook-Abonnement auf Kontoebene und behalten Sie die Abfrage der Aufgabendetails als Bestätigung des Ergebnisses bei.

Fehlerantworten und Fehlercodes

error.tid ist die ID zur Anfrageverfolgung. Geben Sie sie bei einer Anfrage an den technischen Support mit an.

Vollständiges Beispiel

Diese Beispiele erstellen eine asynchrone Aufgabe, fragen sie ab und speichern alle Bilder.