Skip to main content
Anfragen wie Videogenerierung oder Bildgenerierung im Stapel dauern in der Regel länger, als eine einzelne HTTP-Verbindung sinnvoll warten kann. Trennt der Client während einer langen Textgenerierung die Verbindung, lässt sich die bereits erzeugte Antwort nicht mehr abrufen. Asynchrone Aufgaben (Async Tasks) führen diese drei Szenarien in einem gemeinsamen Aufgabenobjekt zusammen: Bild- und Videoanfragen erstellen über die Generierungsendpunkte eine Aufgabe und geben sofort eine task_id zurück; abgebrochene LLM-Anfragen führt die Plattform weiter aus und speichert die finale Antwort. Alle drei nutzen dieselben Aufgabenstatus, denselben Abfrageendpunkt und denselben Ablauf zum Herunterladen der Ergebnisse.
Bitte verwenden Sie zum Abfragen der Aufgabe und zum Herunterladen der Ergebnisse denselben API Key, mit dem die Aufgabe erstellt wurde. Aufgaben sind nach API Key isoliert. Auch zwei Keys desselben Kontos können die Aufgaben des jeweils anderen nicht lesen.

Asynchrone Aufgaben in der Konsole aktivieren

Aktivieren Sie die Funktion für asynchrone Aufgaben für Ihr Konto, bevor Sie asynchrone Bild- oder Videoaufgaben erstellen. Zeigt die Konsole diesen Eintrag noch nicht an, wenden Sie sich an den technischen Support von AIHubMix.
Ist die Funktion für asynchrone Aufgaben nicht aktiviert, geben Anfragen zum Erstellen von Medienaufgaben 403 async_not_enabled zurück. LLM-Anfragen schlagen deshalb nicht fehl, jedoch lässt sich die finale Antwort nach einem Abbruch des Clients nicht abrufen.

1. Schnellstart

Der vollständige Ablauf asynchroner Bild- und Videoaufgaben besteht aus drei Schritten:

2. Synchroner Aufruf und asynchrone Aufgabe im Vergleich

Ein synchroner Aufruf liefert das Ergebnis innerhalb einer HTTP-Antwort; nach einem Verbindungsabbruch ist das Ergebnis nicht mehr abrufbar. Asynchrone Aufgaben speichern das Ergebnis auf der Plattform. Die task_id lässt sich vor Ablauf des Ergebnisses mit demselben API Key erneut abfragen und herunterladen. Das eignet sich für länger laufende Generierungsanfragen sowie für lange Textausgaben, deren finale Antwort nach einem Abbruch abgerufen werden soll.

3. Überblick über die Endpunkte

Base URL: https://aihubmix.com, die Authentifizierung erfolgt per Bearer Token:
/ai/v1/tasks ist ein rein lesender, einheitlicher Abfrageendpunkt; POST /ai/v1/tasks wird nicht angeboten. Bilder und Videos werden jeweils über den zugehörigen Generierungsendpunkt erstellt. Anfragen, die die Bedingungen der LLM-Wiederherstellung nach Abbruch erfüllen, werden nach einem Abbruch des Clients automatisch als llm-Aufgabe erfasst.

4. Unterstützte Modelle

Der unterstützte Umfang asynchroner Aufgaben richtet sich nach dem Aufgabentyp, beim Aufruf sind keine zusätzlichen Parameter nötig.

4.1 Asynchrone Bilder

4.2 Asynchrone Videos

4.3 LLM-Wiederherstellung nach Abbruch

Der unterstützte Umfang wird laufend erweitert, diese Tabelle wird entsprechend aktualisiert.

5. Wie erstellt man asynchrone Aufgaben?

5.1 Asynchrone Bilder

Der Bildendpunkt gibt standardmäßig synchron zurück. Wird async auf true gesetzt, gibt der Endpunkt sofort das Aufgabenobjekt zurück und die Generierung läuft im Hintergrund weiter.
async muss ein boolescher Wert sein. Wird das Feld nicht übergeben oder auf false gesetzt, behält der Bildendpunkt sein synchrones Verhalten.

5.2 Asynchrone Videos

Der Videoendpunkt arbeitet immer asynchron. Nach erfolgreicher Erstellung wird der Status pending oder in_progress zurückgegeben. Ein Umschalten auf synchrones Warten über Prefer: wait wird nicht unterstützt.

5.3 Gemeinsame Parameter

model, prompt, n, seconds und size in den Beispielen sind gängige Modellparameter. Welche Felder und Werte ein Modell unterstützt, richtet sich nach der API-Dokumentation des jeweiligen Modells; für Videomodelle siehe die Dokumentation zur Videogenerierung. Die folgende Tabelle beschreibt nur die Parameter, die alle asynchronen Aufgaben gemeinsam nutzen.
Bildaufgaben können Webhooks nur bei async: true verwenden. Wird webhook_events_filter weggelassen, pusht die Plattform die drei Endstatus completed, failed und cancelled. Bei Angabe muss das Feld zusammen mit webhook_url verwendet werden und darf weder leer sein noch Duplikate enthalten.

6. Wie funktioniert die LLM-Wiederherstellung nach Abbruch?

Die LLM-Wiederherstellung nach Abbruch dient dazu, die finale Antwort nach einem Verbindungsabbruch des Clients abzurufen. Diese Funktion nutzt die bestehende Art der LLM-Anfrage, Streaming-Verhalten und Antwortformat bleiben unverändert. Ein zusätzlicher Endpunkt zum Erstellen ist nicht erforderlich, und es wird vorab keine task_id zurückgegeben.

6.1 Bedingungen für die Wirksamkeit

Die folgenden Bedingungen müssen gleichzeitig erfüllt sein: Unterstützte Endpunkte:
Beim Aufruf sind keine zusätzlichen Felder zu übergeben. Den unterstützten Umfang finden Sie unter 4.3 LLM-Wiederherstellung nach Abbruch. Für Modelle, die dort nicht aufgeführt sind, lässt sich die Wiederherstellung nach Abbruch vor der produktiven Anbindung mit einer kostengünstigen Anfrage prüfen; solche Prüfanfragen werden regulär abgerechnet. Ist eine der Bedingungen nicht erfüllt, wird die Anfrage weiterhin normal ausgeführt, nach einem Abbruch des Clients entsteht jedoch keine llm-Aufgabe.

6.2 Ablauf nach einem Abbruch

Für LLM-Anfragen, die normal abgeschlossen und erfolgreich an den Client zurückgegeben werden, wird keine Aufgabe erstellt; sie erscheinen auch nicht in der Aufgabenliste. Abgebrochene Anfragen erscheinen in der Liste, sobald die finale Antwort gespeichert ist, während der Verarbeitung sind sie daher zeitweise nicht auffindbar.

6.3 Die zugehörige abgebrochene Anfrage finden

Die LLM-Antwortheader enthalten X-Aihubmix-Request-Id. Der Client sollte diesen Wert unmittelbar nach Erhalt der Antwortheader speichern. Nach einem Abbruch lässt sich damit in der Liste der asynchronen Aufgaben in der AIHubMix-Konsole die zugehörige Aufgabe finden. Die öffentliche Aufgaben-API unterstützt derzeit kein Filtern nach Request-ID. Ohne gespeicherte Request-ID bleibt nur die Suche nach Modell und Erstellungszeit, und zwar mit demselben API Key, mit dem die Anfrage erstellt wurde:
Werden mit demselben API Key mehrere Anfragen an dasselbe Modell parallel gestellt, lässt sich allein über Modell und Erstellungszeit keine eindeutige Zuordnung sicherstellen. Wenn Sie eine zuverlässige Wiederherstellung benötigen, speichern Sie X-Aihubmix-Request-Id und suchen Sie über die Konsole. Liegen die Antwortheader nicht vor, sollten Sie die neueste Aufgabe in der Liste nicht ohne Weiteres als die eigene Anfrage einstufen.
Aufgaben der LLM-Wiederherstellung nach Abbruch senden derzeit keine Webhooks, rufen Sie das Ergebnis bitte über die Aufgabenliste ab. Ein Abbruch des Clients stoppt die weitere Verarbeitung auf der Plattform nicht, der Aufruf wird weiterhin nach den Regeln des jeweiligen LLM-Endpunkts abgerechnet.

7. Aufgabenobjekt und Status

Alle Aufgaben verwenden dieselbe Antwortstruktur:
Ergebnisfelder in output:

7.1 Statusbeschreibung

Empfohlen wird eine Abfrage alle 15 Sekunden, bis der Status auf completed, failed oder cancelled wechselt.
Auch Aufgaben mit failed oder cancelled können bereits erzeugte Teilergebnisse enthalten. Prüfen Sie neben dem Status auch, ob output leer ist.

8. Wie fragt man Aufgaben ab?

8.1 Aufgabendetails abfragen

Dieser Endpunkt gibt den zum Abfragezeitpunkt aktuellen Stand der Aufgabe zurück. Die Abfrage verändert die Aufgabe nicht, der Aufgabenstatus wird von der Plattform automatisch aktualisiert.

8.2 Aufgabenliste abfragen

Ist die Antwort bei der Erstellung verloren gegangen oder möchten Sie mehrere zurückliegende Aufgaben einsehen, lässt sich die task_id über den Listenendpunkt wiederfinden:
Beispielantwort:
Die nächste Seite anfordern:

9. Wie ruft man Aufgabenergebnisse ab?

9.1 Aufgaben mit einem Ergebnis

Enthält output nur eine Datei, ist der direkte Zugriff möglich:
Ebenso lässt sich output[0].content_url direkt verwenden. Der Content-Type der Download-Antwort entspricht output[0].content_type.

9.2 Aufgaben mit mehreren Ergebnissen

Enthält output mehrere Dateien, muss die zugehörige result_id angegeben werden:
Wird bei Aufgaben mit mehreren Ergebnissen keine result_id angegeben, gibt der Endpunkt 400 result_id_required zurück.

9.3 LLM-Antwortaufgaben

Sind die Bedingungen der LLM-Wiederherstellung nach Abbruch erfüllt und ist die Antwort gespeichert, hat die Aufgabe im Feld object den Wert llm und der Eintrag in output im Feld type den Wert response. Mögliche Inhaltstypen:
  • application/json: normale JSON-Antwort
  • text/event-stream: gespeicherte SSE-Streaming-Antwort
Die Markierung für das Abschneiden steht in den Aufgabendetails unter output[0].truncated. Der Wert true bedeutet, dass die gespeicherte Antwort wegen einer Größenbeschränkung abgeschnitten wurde. GET /ai/v1/tasks/{task_id}/content gibt den Original-JSON- oder SSE-Inhalt zurück und umschließt ihn nicht zusätzlich mit einem truncated-Feld. Fragen Sie deshalb zuerst die Aufgabendetails ab und lesen Sie danach den Inhalt.
Ergebnisse können ablaufen, und es kann eine Begrenzung der Download-Anzahl geben. Bitte speichern Sie sie rechtzeitig vor expires_at. Nach Ablauf wird 410 artifact_expired zurückgegeben, bei Überschreiten der Download-Grenze 429 too_many_downloads.

10. Wie verwendet man Webhooks?

Derzeit wird ein Webhook auf Aufgabenebene beim Erstellen einer asynchronen Aufgabe unterstützt. Soll AIHubMix Sie nach Abschluss der Aufgabe aktiv benachrichtigen, übergeben Sie webhook_url und optional webhook_events_filter im Request-Body der asynchronen Bild- oder Videoanfrage:
Die Callback-Adresse muss HTTPS verwenden und darf nicht auf den lokalen Rechner, private Netze oder andere eingeschränkte Adressen zeigen.

10.1 Callback-Anfrage

AIHubMix sendet eine POST-Anfrage an die Callback-Adresse:
Für die URLs in results ist weiterhin der API Key erforderlich, mit dem die Aufgabe erstellt wurde.

10.2 Wiederholung und Deduplizierung

Die Plattform versucht die Zustellung mindestens einmal, dasselbe Ereignis kann daher mehrfach gesendet werden:
  • HTTP 2xx bedeutet erfolgreicher Empfang.
  • HTTP 5xx, Netzwerkfehler oder Timeouts lösen eine Wiederholung aus.
  • HTTP 3xx und 4xx werden nicht wiederholt.
  • Maximal 6 Zustellversuche, die Wiederholungsabstände betragen der Reihe nach 1, 4, 16, 64 und 256 Sekunden.
Die empfangende Seite sollte event_id speichern. Trifft dieselbe event_id erneut ein, überspringen Sie die Geschäftslogik und geben Sie direkt 2xx zurück.
Der aktuelle Webhook auf Aufgabenebene bietet keine konfigurierbaren eigenen Signaturzugangsdaten. Rufen Sie nach Erhalt der Benachrichtigung GET /ai/v1/tasks/{task_id} mit dem API Key auf, mit dem die Aufgabe erstellt wurde; maßgeblich ist das Abfrageergebnis.

11. Fehlerantworten und Fehlercodes

Fehlerantworten verwenden eine einheitliche Struktur:

12. Vollständiges Beispiel

Vollständiger Ablauf zum Erstellen einer Videoaufgabe, Abfragen des Status und Herunterladen aller Ergebnisse:

Häufige Fragen

Wie oft sollte der Aufgabenstatus abgefragt werden? Empfohlen wird eine Abfrage alle 15 Sekunden, um häufiges Polling zu vermeiden. Auch bei Verwendung von Webhooks sollte eine Abfrage mit niedriger Frequenz als Absicherung bestehen bleiben. Wie findet man eine Aufgabe wieder, wenn die Antwort bei der Erstellung verloren gegangen ist? Rufen Sie GET /ai/v1/tasks mit demselben API Key auf, mit dem die Aufgabe erstellt wurde. Über object, model und status lässt sich die Treffermenge eingrenzen. Warum findet ein anderer API Key desselben Kontos die Aufgabe nicht? Aufgaben sind nach API Key isoliert. Abfrage-, Download- und Listenanfragen müssen denselben Key verwenden, mit dem die Aufgabe erstellt wurde. Warum ist output kein leeres Array, obwohl die Aufgabe fehlgeschlagen ist? Einige Modelle können vor dem endgültigen Fehlschlag oder Abbruch bereits verwertbare Ergebnisse erzeugt haben. Sobald in output ein content_url oder ein b64_json vorhanden ist, lässt sich das Ergebnis auf dem jeweiligen Weg abrufen. Was tun, wenn kein Webhook eintrifft? Prüfen Sie, ob die Callback-Adresse öffentlich erreichbar ist, HTTPS verwendet und innerhalb von 10 Sekunden 2xx zurückgibt. Unabhängig von der Webhook-Nutzung lässt sich der Endstatus über GET /ai/v1/tasks/{task_id} abfragen. Muss bestehender Code für die LLM-Wiederherstellung nach Abbruch geändert werden? Nein. Die Art der Anfrage, das Streaming-Verhalten und das Antwortformat bleiben unverändert. Es wird empfohlen, den Antwortheader X-Aihubmix-Request-Id zu speichern, um die zugehörige Aufgabe nach einem Abbruch in der Konsole genau zu finden.
Aktualisiert am: 2026-07-28