Bildgenerierung

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.

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

curl https://aihubmix.com/ai/v1/images/{id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

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.

# Text-zu-Bild-Modelle
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# Text-zu-Video-Modelle
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

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.

Feld	Beschreibung
`data[].model_id`	Modell-ID für Generierungsanfragen und nachfolgende Schema-Anfragen
`data[].model_name`	Anzeigename des Modells
`data[].types`	Kommagetrennte Modelltypen, möglicherweise mit `image_generation` und `llm`
`data[].input_modalities`	Kommagetrennte Eingabemodalitäten
`data[].schema_checked`	`true`, wenn das Anfrageschema veröffentlicht und geprüft wurde

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

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.

# Text-zu-Bild-Modell
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# Text-zu-Video-Modell
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

Die Antwort enthält für modality den Wert image oder video. Jeder Eintrag im Array endpoints beschreibt ein verfügbares Aufrufprotokoll.

Feld	Beschreibung
`default_endpoint`	Kennung des Standardendpunkts für das Modell
`endpoints[].endpoint`	Endpunktkennung
`endpoints[].method`	HTTP-Methode, zum Beispiel `POST`
`endpoints[].path`	Anfragepfad
`endpoints[].content_types`	Vom Endpunkt akzeptierte Inhaltstypen
`endpoints[].lifecycle`	Synchroner oder asynchroner Modus, Abfragepfad und Statuswerte
`endpoints[].request.schema`	Vollständiges Anfrage-JSON-Schema für dieses Modell und diesen Endpunkt mit Pflichtfeldern und Wertebeschränkungen

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.

# Text-zu-Bild
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# Text-zu-Video
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

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:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

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:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

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

Feld	Typ	Erforderlich	Beschreibung
`model`	string	Ja	Modellname
`prompt`	string	Ja	Bildbeschreibung; darf nicht leer sein
`n`	integer/null	Nein	Anzahl der Bilder, Mindestwert `1`, Standardwert `1`
`size`	string/null	Nein	`{width}x{height}`, zum Beispiel `1024x1024`
`aspect_ratio`	string/null	Nein	Seitenverhältnis; alternativ zu `size`
`seed`	integer/null	Nein	Zufallsstartwert
`negative_prompt`	string/null	Nein	Negativer Prompt
`image`	string/object	Nein	Einzelnes Eingabebild als URL, Data URI, Base64 oder `{url}`-Objekt
`images`	array/null	Nein	Mehrere Eingabebilder
`mask`	string/object	Nein	Maske für die Bildbearbeitung
`output_format`	string/null	Nein	`png`, `jpeg` oder `webp`; Standardwert `png`
`response_format`	string/null	Nein	`url` oder `b64_json`; Standardwert `url`
`async`	boolean	Nein	Führt die Aufgabe asynchron aus, wenn der Wert `true` ist
`webhook_url`	string	Nein	HTTPS-Callback-URL mit maximal 512 Zeichen
`webhook_events_filter`	string[]	Nein	Nicht leere Teilmenge von `completed`, `failed` und `cancelled`
`extra`	object/null	Nein	Modellspezifische Zusatzparameter

Objekt einer Medienaufgabe

Die dedizierten Endpunkte für Bilder und Videos geben folgende Struktur zurück:

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

Feld	Typ	Beschreibung
`id`	string	Aufgaben-ID der Plattform
`object`	string	`image` oder `video`
`model`	string	Modellname
`status`	string	Aktueller Aufgabenstatus
`output`	array	Bereits generierte Ergebnisse; leeres Array, solange kein Ergebnis vorliegt
`error`	object/null	Fehlerinformationen; kann `code`, `message` und `upstream_detail` enthalten
`created_at`	integer	Erstellungszeit als Unix-Zeit in Sekunden
`completed_at`	integer/null	Zeitpunkt des endgültigen Status als Unix-Zeit in Sekunden
`expires_at`	null	Dedizierte Medienendpunkte geben derzeit `null` zurück

Einträge in output für Medien:

Feld	Typ	Beschreibung
`index`	integer	Reihenfolge des Ergebnisses, beginnend mit `0`
`type`	string	Derzeit `file`
`content_url`	string/null	URL zum Herunterladen des Ergebnisses
`b64_json`	string/null	Base64-codiertes Bildergebnis

Statusbeschreibung

Status	Beendet	Beschreibung
`pending`	Nein	Die Plattform hat die Aufgabe angenommen; sie wartet auf die Ausführung
`in_progress`	Nein	Die Aufgabe wird ausgeführt
`completed`	Ja	Die Aufgabe ist abgeschlossen; `output` kann gelesen werden
`failed`	Ja	Die Aufgabe ist fehlgeschlagen; die Ursache steht in `error`
`cancelled`	Ja	Die Aufgabe wurde abgebrochen

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

# Bild
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Video
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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:

curl "https://aihubmix.com/ai/v1/images?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parameter	Typ	Standardwert	Beschreibung
`after`	string	-	Cursor für die Seitennavigation; verwenden Sie `next_after` der vorherigen Seite
`limit`	integer	`20`	Anzahl pro Seite, maximal `100`
`order`	string	`desc`	Mit `asc` aufsteigend; alle anderen Werte werden als `desc` behandelt

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "image",
      "model": "qwen-image-2.0",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

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:

curl "https://aihubmix.com/ai/v1/tasks?object=image&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parameter	Typ	Standardwert	Beschreibung
`object`	string	-	`llm`, `image` oder `video`
`status`	string	-	`pending`, `in_progress`, `completed`, `failed` oder `cancelled`
`model`	string	-	Exakte Filterung nach Modellname
`after`	string	-	Cursor für die Seitennavigation
`limit`	integer	`20`	Bereich von `1` bis `100`
`order`	string	`desc`	`asc` oder `desc`

Details einer einheitlichen Aufgabe:

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Einheitlicher output-Eintrag einer Medienaufgabe:

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

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:

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

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:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

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

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

Feld	Beschreibung
`event_id`	ID des Callback-Ereignisses zur Deduplizierung
`event_type`	`completed`, `failed` oder `cancelled`
`created_at`	Ereigniszeit im Format RFC 3339
`data.task_id`	Aufgaben-ID der Plattform
`data.status`	Aktueller endgültiger Status
`data.model`	Modellname
`data.results[].url`	URL zum Herunterladen des Ergebnisses, die nach Abschluss enthalten sein kann
`data.error`	Fehlerinformationen, die bei einem Fehlschlag enthalten sein können

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

Dieser Abschnitt gilt für /ai/v1/images/* und Bildaufgaben. Videofehler finden Sie in der Video-API.

Fehler der aktuellen Anfrage: Ein HTTP-Status außerhalb von 2xx bedeutet, dass die aktuelle Anfrage zum Erstellen, Abfragen oder Herunterladen fehlgeschlagen ist. Siehe Fehler bei HTTP-Anfragen.
Fehler bei der Aufgabenausführung: Die Abfrage liefert HTTP 200, die Aufgabe hat jedoch status=failed. Die Ursache steht im Feld error der Aufgabe. Siehe Fehler bei der Aufgabenausführung.
Lesefehler beim Ergebnis einer einzelnen Listenzeile: Die Liste liefert HTTP 200, eine Aufgabe enthält jedoch output_error. Siehe Lesefehler bei einzelnen Listenergebnissen.

Die Spalten message enthalten die englischen Antwortmeldungen. Die Beschreibungen erläutern deren Bedeutung und die erforderlichen Schritte. Für Fehler bei der Parametervalidierung sind allgemeine Meldungen angegeben; die tatsächliche Antwort kann konkrete Felder und Einschränkungen nennen. Clients sollten den Fehlertyp anhand von code bestimmen und sich nicht auf den Abgleich der vollständigen message verlassen.

{
  "error": {
    "message": "The task was not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

HTTP-5xx-Fehler melden

Wenn eine Anfrage HTTP 5xx zurückgibt, melden Sie den Fehler und geben Sie error.tid an.

Fehler bei HTTP-Anfragen

Die folgenden HTTP-Statuscodes gelten für direkte Fehler der aktuellen Anfrage. Fehler bei der Ausführung einer bereits erstellten Aufgabe finden Sie weiter unten in der Tabelle zu Fehlern bei der Aufgabenausführung.

Anfrageparameter und Medieneingaben

HTTP	`code`	`message`	Beschreibung
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	Der Anfragetext, die Abfrageparameter oder die Parametertypen sind fehlerhaft. Prüfen Sie anhand der Fehlermeldung das Anfrageformat sowie die Typen und Werte der Parameter.
404	`model_not_found`	`The requested model was not found. Check the model name.`	Das angeforderte Modell existiert nicht. Prüfen Sie den Modellnamen.
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	Die Parameter entsprechen nicht den Eingabeanforderungen des gewählten Modells. Prüfen Sie das Modellschema und korrigieren Sie die in der Fehlermeldung genannten Felder.
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	Das Modell unterstützt diese Kombination aus Vorgang und Medieneingaben nicht. Ändern Sie die Eingabekombination oder wählen Sie ein Modell, das sie unterstützt.
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	Die angeforderten Parameter überschreiten die Fähigkeiten des Modells. Passen Sie sie gemäß der Fehlermeldung an oder wählen Sie ein anderes Modell.
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	Das Modell unterstützt dieses Medienformat nicht. Verwenden Sie ein Format aus der Fehlermeldung oder aus `error.details.allowed_mime_types`. Falls keine Liste angegeben ist, prüfen Sie die Eingabeanforderungen des Modells.
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	Die Mediendaten sind nachweislich ungültig, etwa durch beschädigte Base64-Daten oder eine fehlerhafte Data-URI-Struktur. Prüfen Sie Datenintegrität und Kodierung und stellen Sie erneut gültige Medien bereit.
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	Die Medien-URL ist nicht erreichbar oder kann nicht gelesen werden. Prüfen Sie, ob sie gültig und öffentlich zugänglich ist und gültige Medieninhalte zurückgibt.
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	Die Medieneingabe konnte nicht verarbeitet werden; eine genauere Ursache lässt sich derzeit nicht bestätigen. Prüfen Sie, ob die Daten oder die URL gültig sind und das Modell das Format unterstützt.
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	Der Medieninhalt der Bildaufgabe überschreitet die aktuelle Verarbeitungsgrenze. Verkleinern Sie ihn gemäß `error.details.max_bytes` oder der Grenze in der Fehlermeldung und versuchen Sie es erneut.
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	Der gesamte HTTP-Anfragetext überschreitet 32 MiB. Verkleinern Sie den tatsächlich gesendeten Anfragetext einschließlich Text, Parametern und der Kodierung eingebetteter Medien.

Größenbeschränkungen

Mediengröße: Bildaufgaben, die die Grenze überschreiten, geben image_too_large zurück. Die genaue Grenze steht in der Fehlermeldung oder in error.details.max_bytes.
Gesamte Anfragegröße: request_too_large bedeutet, dass der HTTP-Anfragetext 32 MiB überschreitet, einschließlich Text, Parametern und der Kodierung eingebetteter Medien. Wird nur eine URL übermittelt, zählt die URL selbst zum Anfragetext; die referenzierte Datei muss weiterhin die Mediengrenzen des Modells einhalten.
Tatsächliche Größe: error.details.actual_bytes wird nur angegeben, wenn die vollständige Größe bestätigt ist. Wird ein Medium über eine URL gelesen und beim Erreichen der Grenze abgebrochen, kann dieses Feld fehlen.

Unterstützte Formate Die unterstützten Formate hängen vom gewählten Modell ab. Prüfen Sie zuerst error.details.allowed_mime_types oder die Formatliste in der Fehlermeldung. Falls keine Liste angegeben ist, lesen Sie das Schema des Modells. Platzhalter in Meldungen

{media_kind}: Der tatsächliche Medientyp. Wenn der Typ bestätigt ist, verwenden auch die Meldungen für invalid_media_data und media_url_unreachable den Wert image oder video.
{max_bytes}: Die Größenbeschränkung in Bytes. Ist die Bildgrenze unbekannt, lautet die Antwort The image is too large. Reduce the image size and try again.
{allowed_formats}: Die Liste zulässiger Formate. Meldungen zu Formatfehlern können Use one of: {allowed_formats}. anhängen.

Generierungsanfragen und zurückgegebene Ergebnisse

HTTP	`code`	`message`	Beschreibung
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	Der Modellanbieter hat die Anfrage abgeschlossen, aber kein nutzbares Bild zurückgegeben. Passen Sie die Anfrage an oder wählen Sie ein anderes Modell und versuchen Sie es erneut. Bei anhaltenden Fehlern kontaktieren Sie den Support mit der Anfrage-ID. Wiederholen Sie die Generierung nicht bedingungslos automatisch allein aufgrund von HTTP 502.
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	Der Modellanbieter hat den generierten Inhalt blockiert und kein nutzbares Bild zurückgegeben. Ändern Sie den Prompt oder die Eingabe und versuchen Sie es erneut. Für diesen Versuch fallen keine Generierungskosten an.
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	Der Modellanbieter hat die Anfrage abgelehnt. Dieser Code allein belegt keinen Verstoß gegen Inhaltsrichtlinien. Prüfen und ändern Sie die Anfrageparameter und Eingabeinhalte und versuchen Sie es erneut.
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	Der Modellanbieter hat eine Antwort geliefert, die die Plattform nicht verarbeiten konnte. Dies bestätigt nicht, dass kein Ergebnis generiert wurde. Kontaktieren Sie den Support mit der Anfrage-ID; schließen Sie daraus nicht selbst auf einen Parameterfehler oder ein leeres Ergebnis.
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao hat einen bestimmten Ablehnungscode zum Datenschutz bei Bildern realer Personen zurückgegeben. Schließen Sie zunächst die Identitätsprüfung ab und verwenden Sie dann ein aktiviertes `asset://`-Asset. Siehe die Dokumentation zu Assets realer Personen.
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	Die Generierung wurde innerhalb der Wartezeit nicht abgeschlossen. Eine Zeitüberschreitung beweist nicht, dass die Anfrage nicht ausgeführt wurde. Kontaktieren Sie den Support mit der Anfrage-ID; fragen Sie keine Aufgaben-ID ab, die Ihnen nicht zurückgegeben wurde.
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	Die Aufgabe wurde an den Modellanbieter übermittelt, ihr weiterer Status lässt sich jedoch nicht bestätigen. Reichen Sie sie nicht erneut ein. Kontaktieren Sie den Support mit der Anfrage-ID und geben Sie, falls vorhanden, auch die Aufgaben-ID an.

Konto und Berechtigungen

HTTP	`code`	`message`	Beschreibung
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	Der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Header `Authorization` und den API-Schlüssel.
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	Das Kontingent des Kontos reicht nicht aus. Laden Sie Guthaben auf und versuchen Sie es erneut.
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	Das Konto oder der API-Schlüssel hat keinen Zugriff. Prüfen Sie die Berechtigungen des Kontos und des API-Schlüssels sowie die IP-Beschränkungen.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	Asynchrone Aufgaben sind für das Konto nicht aktiviert. Aktivieren Sie sie über den Konsolenlink in der Antwort und versuchen Sie es erneut.

Dienstverfügbarkeit und Ratenbegrenzung

HTTP	`code`	`message`	Beschreibung
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	Die Anfragen erfolgen zu häufig. Reduzieren Sie die Anfragerate und versuchen Sie es erneut.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	Der Modellanbieter begrenzt die Anfragerate. Versuchen Sie es später erneut und vermeiden Sie wiederholte sofortige Übermittlungen.
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	Auf der Plattform ist ein interner Fehler aufgetreten. Kontaktieren Sie den Support mit der Anfrage-ID. Gültige Eingaben müssen nicht wiederholt geändert werden.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Der Modellanbieter ist vorübergehend nicht verfügbar, möglicherweise aufgrund eines Verbindungsfehlers, eines Dienstfehlers des Anbieters oder eines Fehlers beim Lesen der Antwort. Dieser Code allein bestätigt nicht, ob ein Ergebnis generiert wurde. Bei anhaltenden Fehlern kontaktieren Sie den Support mit der Anfrage-ID.
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	Der Modellanbieter ist nicht verfügbar. Die Tabelle zeigt die Standardmeldung; die tatsächliche Antwort kann genauere Hinweise enthalten. Bestimmen Sie den Fehlertyp anhand von `code`. Kontaktieren Sie den Support mit der Anfrage-ID.
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	Das angeforderte Modell ist vorübergehend nicht verfügbar. Versuchen Sie es später erneut oder wählen Sie ein anderes Modell. Bei anhaltenden Fehlern kontaktieren Sie den Support mit der Anfrage-ID.
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	Der Dienst ist vorübergehend nicht verfügbar. Wiederholen Sie den aktuellen Vorgang später. Wiederholen Sie bei einem Downloadfehler den Download, ohne erneut zu generieren.

provider_unavailable weist auf einen eindeutig festgestellten Fehler des Modellanbieters hin. Ein allgemeiner Status 429 oder 4xx allein bestätigt kein Problem mit dem Kontingent, der Inhaltsmoderation oder den Parametern.

Aufgabenabfragen und Ergebnisdownloads

HTTP	`code`	`message`	Beschreibung
404	`task_not_found`	`The task was not found.`	Die Aufgabe existiert nicht oder gehört nicht zum aktuellen Konto. Prüfen Sie die Aufgaben-ID und stellen Sie sicher, dass der API-Schlüssel zum Konto gehört, das die Aufgabe erstellt hat.
404	`result_not_found`	`The result was not found.`	Das Ergebnis existiert nicht oder ist nicht zugänglich. Prüfen Sie Aufgaben-ID, Ergebnis-ID und API-Schlüssel. Eine bekanntermaßen ungültige Ergebnis-ID wird nicht allein deshalb zu einem Fehler 409, weil die Aufgabe noch ausgeführt wird.
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	Der Seitencursor ist ungültig oder abgelaufen. Entfernen Sie `after`, beginnen Sie erneut bei der ersten Seite und verwenden Sie den neuen Cursor aus dieser Liste.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	Die Aufgabe hat mehrere Ergebnisse, aber `result_id` wurde nicht angegeben. Wählen Sie ein Ergebnis aus der Aufgabenausgabe und geben Sie dessen `result_id` an.
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	Die Aufgabe wartet noch oder wird ausgeführt; das Ergebnis ist noch nicht bereit. Fragen Sie den Aufgabenstatus weiter ab und laden Sie das Ergebnis herunter, sobald es bereitsteht. Eine erneute Generierung ist nicht erforderlich.
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	Die Aufbewahrungsdauer des Ergebnisses ist abgelaufen. Abgelaufene Ergebnisse können nicht mehr heruntergeladen werden. Stellen Sie bei Bedarf eine neue Generierungsanfrage.
429	`too_many_downloads`	`Download limit exceeded for this result.`	Die Downloadgrenze wurde erreicht. Prüfen Sie bereits gespeicherte Ergebnisse. Allein durch Warten wird die verfügbare Anzahl an Downloads nicht garantiert wiederhergestellt.

Fehler bei der Aufgabenausführung

Nach erfolgreicher Erstellung einer Aufgabe werden Generierungsfehler durch status=failed und das Feld error der Aufgabe gemeldet. Eine erfolgreiche Abfrage liefert weiterhin HTTP 200.

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

Task `code`	`message`	Beschreibung
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	Der Modellanbieter hat die Anfrage abgeschlossen, aber kein nutzbares Bild zurückgegeben. Passen Sie die Anfrage an oder wählen Sie ein anderes Modell und reichen Sie eine neue Aufgabe ein. Wiederholen Sie die Generierung nicht bedingungslos automatisch.
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	Der Modellanbieter hat den generierten Inhalt blockiert und kein nutzbares Bild zurückgegeben. Ändern Sie den Prompt oder die Eingabe und reichen Sie eine neue Aufgabe ein. Für diesen Versuch fallen keine Generierungskosten an.
`output_policy_violation`	`Generated content was rejected by the content policy.`	Der generierte Inhalt hat die Moderation nicht bestanden. Ändern Sie den Prompt oder die Eingabe und reichen Sie eine neue Aufgabe ein. Es gelten die bestehenden Abrechnungsregeln für die Inhaltsmoderation; frühere Kosten entnehmen Sie den Abrechnungsaufzeichnungen.
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	Der Modellanbieter hat die Anfrage abgelehnt. Dieser Code allein belegt keinen Verstoß gegen Inhaltsrichtlinien. Prüfen und ändern Sie die Anfrageparameter und Eingabeinhalte und reichen Sie eine neue Aufgabe ein.
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	Die Plattform konnte die Antwort des Modellanbieters nicht verarbeiten. Dies bestätigt nicht, dass kein Ergebnis generiert wurde. Kontaktieren Sie den Support mit der Aufgaben-ID.
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	Die Aufgabe wurde an den Modellanbieter übermittelt, ihr weiterer Status lässt sich jedoch nicht bestätigen. Reichen Sie sie nicht erneut ein. Kontaktieren Sie den Support mit der Aufgaben-ID.
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	Ein generiertes Ergebnis liegt vor, aber die Plattform konnte das Speichern oder Bereitstellen nicht abschließen. Generieren Sie nicht automatisch erneut. Kontaktieren Sie den Support mit der Aufgaben-ID, um zuerst das vorhandene Ergebnis prüfen zu lassen.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	Der Modellanbieter begrenzt die Anfragerate. Versuchen Sie es später erneut und vermeiden Sie wiederholte sofortige Übermittlungen.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Während der Aufgabenausführung trat ein Verbindungsfehler zum Modellanbieter, ein Dienstfehler des Anbieters oder ein Fehler beim Lesen seiner Antwort auf. Dieser Code allein bestätigt nicht, ob ein Ergebnis generiert wurde. Bei anhaltenden Fehlern kontaktieren Sie den Support mit der Aufgaben-ID.
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	Der Modellanbieter ist nicht verfügbar. Die Tabelle zeigt die Standardmeldung; die tatsächliche Antwort kann genauere Hinweise enthalten. Bestimmen Sie den Fehlertyp anhand von `code`. Kontaktieren Sie den Support mit der Aufgaben-ID.
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao hat einen bestimmten Ablehnungscode zum Datenschutz bei Bildern realer Personen zurückgegeben. Schließen Sie zunächst die Identitätsprüfung ab und verwenden Sie dann ein aktiviertes `asset://`-Asset. Siehe die Dokumentation zu Assets realer Personen.
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	Die Generierungsaufgabe hat das Zeitlimit überschritten. Kontaktieren Sie den Support mit der Aufgaben-ID.
`internal_error`	`An internal error occurred. Contact support with the task ID.`	Auf der Plattform ist ein interner Fehler aufgetreten. Kontaktieren Sie den Support mit der Aufgaben-ID. Gültige Eingaben müssen nicht wiederholt geändert werden.

Fehler bei Medieneingaben können auch in fehlgeschlagenen Aufgaben erscheinen. Die Codes haben dieselbe Bedeutung wie in der obigen Tabelle zu Medieneingaben; erfolgreiche Abfragen liefern weiterhin HTTP 200. Bei Fehlern zur Mediengröße endet message mit submit a new task. und fordert dazu auf, das Medium vor dem Einreichen einer neuen Aufgabe zu verkleinern. output_blocked bedeutet eine ausdrückliche Blockierung ohne zurückgegebenes nutzbares Bild; für diesen Versuch fallen keine Generierungskosten an. Für output_policy_violation gelten die bestehenden Abrechnungsregeln für die Inhaltsmoderation. Frühere Kosten entnehmen Sie den Abrechnungsaufzeichnungen.

Lesefehler bei einzelnen Listenergebnissen

Einzelne Zeilen in Bild- und Videoaufgabenlisten können output_error enthalten:

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

Dieses Feld zeigt an, dass die Ausgabe dieser Zeile bei der aktuellen Anfrage nicht gelesen werden konnte. Die Liste liefert weiterhin HTTP 200 und für diese Zeile output=[]. Die ursprünglichen Werte von id, status und error sowie die Paginierung bleiben unverändert; andere lesbare Aufgaben sind nicht betroffen. Prüfen Sie auch bei status=completed das Feld output_error, bevor Sie beurteilen, ob das Ergebnis gelesen werden kann. Kontaktieren Sie den Support mit output_error.tid. Falls dieses Feld keine tid enthält, geben Sie die Anfrage-ID aus den aktuellen Antwortheadern an. Dieser Fehler ändert weder den Aufgabenstatus noch die Kosten und löst keinen Webhook aus. Bild- und Videolisten behalten einen bereits ermittelten Wert für expires_at bei. Zeilen mit nicht lesbarer Ausgabe in der einheitlichen Liste /ai/v1/tasks können expires_at=null zurückgeben; für die Ergebnisse gilt weiterhin die ursprüngliche Aufbewahrungsdauer. Diese Behandlung gilt nur, wenn die Ausgabe einer einzelnen Zeile nicht gelesen werden kann und keine Rückfallmöglichkeit verfügbar ist. Schlägt die Abfrage eines gesamten Stapels in der einheitlichen Aufgaben-API fehl, wird weiterhin ein HTTP-Fehler zurückgegeben; derselbe Fehlertyp beim Lesen von Aufgabendetails liefert weiterhin HTTP 500. Verwandte Dokumentation: Bild-API · Video-API · Asynchrone Aufgaben

Vollständiges Beispiel

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

import base64
import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

Erste Schritte

Gateway-Funktionen

Modellfähigkeiten

Protokoll-Referenz

Plattform-Verwaltung

Schnellstart

Wie findet man asynchrone Medienmodelle und ruft ihre Schemas ab?

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

Anfrageschema eines einzelnen Modells abrufen

Wie erstellt man Bildaufgaben?

Synchrone Bilder

Asynchrone Bilder

Standardfelder für Bilder

Objekt einer Medienaufgabe

Statusbeschreibung

Wie fragt man Medienaufgaben ab?

Mediendetails abfragen

Medienliste abfragen

Wie verwendet man einheitliche Aufgabenendpunkte?

Medienergebnisse herunterladen

Bilder herunterladen

Webhooks verwenden

Callback-Anfrage

Wiederholungsversuche und Deduplizierung

Fehlerantworten und Fehlercodes

HTTP-5xx-Fehler melden

Fehler bei HTTP-Anfragen

Anfrageparameter und Medieneingaben

Generierungsanfragen und zurückgegebene Ergebnisse

Konto und Berechtigungen

Dienstverfügbarkeit und Ratenbegrenzung

Aufgabenabfragen und Ergebnisdownloads

Fehler bei der Aufgabenausführung

Lesefehler bei einzelnen Listenergebnissen

Vollständiges Beispiel

​Schnellstart

​Wie findet man asynchrone Medienmodelle und ruft ihre Schemas ab?

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

​Anfrageschema eines einzelnen Modells abrufen

​Wie erstellt man Bildaufgaben?

​Synchrone Bilder

​Asynchrone Bilder

​Standardfelder für Bilder

​Objekt einer Medienaufgabe

​Statusbeschreibung

​Wie fragt man Medienaufgaben ab?

​Mediendetails abfragen

​Medienliste abfragen

​Wie verwendet man einheitliche Aufgabenendpunkte?

​Medienergebnisse herunterladen

​Bilder herunterladen

​Webhooks verwenden

​Callback-Anfrage

​Wiederholungsversuche und Deduplizierung

​Fehlerantworten und Fehlercodes

HTTP-5xx-Fehler melden

​Fehler bei HTTP-Anfragen

​Anfrageparameter und Medieneingaben

​Generierungsanfragen und zurückgegebene Ergebnisse

​Konto und Berechtigungen

​Dienstverfügbarkeit und Ratenbegrenzung

​Aufgabenabfragen und Ergebnisdownloads

​Fehler bei der Aufgabenausführung

​Lesefehler bei einzelnen Listenergebnissen

​Vollständiges Beispiel

Schnellstart

Wie findet man asynchrone Medienmodelle und ruft ihre Schemas ab?

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

Anfrageschema eines einzelnen Modells abrufen

Wie erstellt man Bildaufgaben?

Synchrone Bilder

Asynchrone Bilder

Standardfelder für Bilder

Objekt einer Medienaufgabe

Statusbeschreibung

Wie fragt man Medienaufgaben ab?

Mediendetails abfragen

Medienliste abfragen

Wie verwendet man einheitliche Aufgabenendpunkte?

Medienergebnisse herunterladen

Bilder herunterladen

Webhooks verwenden

Callback-Anfrage

Wiederholungsversuche und Deduplizierung

Fehlerantworten und Fehlercodes

Fehler bei HTTP-Anfragen

Anfrageparameter und Medieneingaben

Generierungsanfragen und zurückgegebene Ergebnisse

Konto und Berechtigungen

Dienstverfügbarkeit und Ratenbegrenzung

Aufgabenabfragen und Ergebnisdownloads

Fehler bei der Aufgabenausführung

Lesefehler bei einzelnen Listenergebnissen

Vollständiges Beispiel