Schnellstart
Der native Bildendpunkt arbeitet standardmäßig synchron. Setzen Sie den booleschen Wertasync 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 diemodel_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 Sietype=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.
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.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.
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 Sieasync weglassen oder auf false setzen, wartet der Endpunkt auf den Abschluss der Generierung und gibt anschließend das Aufgabenobjekt zurück:
GET /ai/v1/images suchen.
Asynchrone Bilder
Wenn Sieasync auf den booleschen Wert true setzen, gibt der Endpunkt sofort ein Aufgabenobjekt zurück und die Generierung wird im Hintergrund fortgesetzt:
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
Medienliste abfragen
Falls die Erstellungsantwort verloren geht, können Sie die Aufgaben-ID über die entsprechende Medienliste wiederfinden:Wie verwendet man einheitliche Aufgabenendpunkte?
Die einheitlichen Aufgabenendpunkte unterstützen folgende Filter:
Details einer einheitlichen Aufgabe:
output-Eintrag einer Medienaufgabe:
/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 dieoutput[].content_url jedes Eintrags im Medienaufgabenobjekt an:
/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
2xxkennzeichnet einen erfolgreichen Empfang. - HTTP
5xx, Netzwerkfehler oder Zeitüberschreitungen lösen einen erneuten Versuch aus. - Bei HTTP
3xxund4xxerfolgt kein erneuter Versuch. - Es erfolgen höchstens 6 Zustellversuche mit Abständen von 1, 4, 16, 64 und 256 Sekunden.
event_id speichern und beim erneuten Empfang desselben Ereignisses direkt 2xx zurückgeben.
Fehlerantworten und Fehlercodes
error.tid ist die ID zur Anfrageverfolgung. Geben Sie sie bei einer Anfrage an den technischen Support mit an.