KI-Video-API wählen: asynchrone Jobs, Webhooks und Erstattungen

Eine KI-Video-API auszuwählen ist etwas anderes, als eine Bild-API auszuwählen. Ein Video-Render dauert Minuten statt Sekunden, und deshalb entscheidet die Form der Integration – nicht die Qualität der Frames –, wie viel von deiner Woche sie dich kostet. Wählst du das falsche Job-Modell, schreibst du später deine Queue, deine Retries und deinen Abrechnungsabgleich neu. Hier sind die sieben Punkte, die du prüfen solltest, bevor du den ersten Request schreibst, mit den Schnittstellen von eroq als durchgerechnetem Beispiel.

1. Asynchrone Jobs statt blockierender Aufrufe

Ein blockierender HTTP-Request, der auf ein Video wartet, ist eine Falle, die sich als Komfort tarnt. Load Balancer, Serverless-Plattformen und CDNs haben alle Request-Obergrenzen, die weit unter der Dauer eines langen Renders liegen. Eine blockierende API funktioniert also im Test und stirbt in der Produktion genau in dem Moment, in dem ein Render länger dauert als sonst.

Die richtige Form ist ein Job. Bei eroq liefert POST /v1/videos/generations sofort eine Job-ID zurück; danach pollst du GET /v1/videos/generations/{id} oder wartest auf einen Webhook. Die vollständige Referenz findest du unter /docs/video.

# 1. submit
curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-lite",
    "prompt": "A courier weaves a bicycle between stopped cars on a wet avenue at dusk, headlights smearing across the frame. Tracking shot, 35mm film, anamorphic lens, neon noir palette, dynamic tempo.",
    "seconds": 5,
    "aspect": "9:16"
  }'

# 2. poll (or skip this and use a webhook)
curl https://eroq.ai/v1/videos/generations/JOB_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"

Was du bei anderen Anbietern prüfen solltest: ob der Video-Endpoint wirklich asynchron ist und ob es einen List-Endpoint gibt, über den du Jobs nach einem Prozessneustart wiederfindest. Wenn der einzige Nachweis eines Renders die Antwort ist, die du verloren hast, wirst du Renders verlieren.

2. Webhooks, die du wirklich verifizieren kannst

Polling ist für den Anfang in Ordnung und bei großem Volumen Verschwendung. Ein Webhook sollte signiert ankommen, und zwar mit einem Signaturverfahren, das du schon einmal implementiert hast.

eroq sendet video.generation.succeeded und video.generation.failed mit einem Signatur-Header im Stil von Stripe, und der Payload enthält eine CDN-URL statt eingebettetem Base64. Das ist wichtig, denn ein JSON-Body mit mehreren Megabyte wird früher oder später irgendetwas in deinem Stack zum Absturz bringen.

Drei Fragen an jeden Anbieter: Ist der Payload signiert, gibt es ein Replay-Fenster im signierten Material, und enthält der Body eine URL oder die Bytes selbst? Prüf die Antworten in der jeweiligen Doku, Stand September 2026.

3. Was passiert, wenn ein Render fehlschlägt

Das ist das Kriterium, das eine echte Plattform von einem Wrapper unterscheidet, und es steht fast nie auf der Preisseite. Stell drei Fragen:

Werden Fehlschläge erstattet? Bei eroq werden fehlgeschlagene Generierungen automatisch erstattet. Du gleichst Erfolge ab, nicht Versuche.

Werden Ablehnungen durch die Richtlinie berechnet? Ein blockierter Request liefert content_blocked zurück und wird nie berechnet. Bei großem Volumen lässt dich eine Plattform, die Ablehnungen abrechnet, für ihren eigenen Filter bezahlen.

Kommt die Prüfung vor oder nach der Abbuchung? Ein Modell, das dein Plan nicht enthält, liefert 403 plan_required zurück, bevor sich auch nur ein Credit bewegt; eine Engine ohne bereitgestellte Kapazität liefert 503 model_unavailable, ebenfalls vor der Abbuchung. Und es gibt auch keinen stillen Fallback auf eine andere Engine: Wenn du ein bestimmtes Modell angefragt hast und es nicht verfügbar ist, bekommst du einen Fehler, keinen Überraschungs-Renderer. Ein stiller Fallback ist der schlimmste Fehlermodus in dieser Kategorie, denn dein Output ändert sich, deine Logs aber nicht.

4. Die Abrechnungseinheit

Zwei Modelle dominieren: sekundengenaue Abrechnung und pauschale Credits pro Clip zu festen Ankerpunkten. Feste Anker lassen sich leichter budgetieren und einem Finanzteam leichter erklären; sekundengenaue Abrechnung ist bei krummen Längen fairer. Keines davon ist falsch, aber du musst wissen, welches für dich gilt, bevor du einem Kunden einen Preis zusagst.

eroq rechnet Credits zu festen Ankern pro Engine ab: 120 Credits für 5 Sekunden mit Seedance 1.0 Lite, 60 mit Motion One, 170 mit Kling 2.5 Turbo, 216 für die festen 8 Sekunden von Veo 3 Fast und so weiter für das gesamte Angebot unter /models. Ein Credit entspricht beim Einstiegspaket etwa einem Cent. Credits verfallen nie, und ein Workspace hat ein gemeinsames Guthaben für alle Plätze und Schlüssel. Deshalb ist die Abrechnung pro Kunde deine Aufgabe statt eines Haufens separater Abrechnungsbeziehungen. Wenn du Generierungen weiterverkaufst, findest du die Mechanik zur Weitergabe nutzungsbasierter Kosten in Credit-Preise für KI-APIs.

5. Rate Limits, die mit dem Plan wachsen

Die Limits pro Schlüssel beginnen bei eroq mit 60 Requests pro Minute für Chat, 20 für Bilder und 6 für Video und Sprache, multipliziert mit dem Plan: ×2 bei Creator, ×4 bei Studio, ×6 bei Team, ×8 bei Agency. Auch die Anzahl der Schlüssel wächst mit dem Plan: 10 Schlüssel bei Hobby, 20 bei Creator, 50 bei Studio, 100 bei Team, 200 bei Agency. Die Ausnahme sind Plätze: Jeder Einzelplan endet bei 2, und ein echtes Team wechselt zu Team (25 Plätze) oder Agency (50).

Der praktische Rat: Gib einen Schlüssel pro Umgebung und einen pro kundenseitiger Oberfläche aus, damit eine außer Kontrolle geratene Schleife im Staging auch nur das Staging drosselt. Prüf bei jedem Anbieter, ob die Limits pro Schlüssel oder pro Konto gelten, denn beides führt zu einem sehr unterschiedlichen Schadensradius.

6. Discovery, damit du das Angebot nicht hartcodierst

Das Angebot ändert sich. Schreibst du Engine-IDs und Preise fest in deine App, lieferst du ein veraltetes Menü aus.

GET /v1/engines liefert jede Engine mit ihrer Plan-Freigabe, ihrer Verfügbarkeit und ihren Fähigkeiten, also ob sie einen Seed, einen Endframe, einen Negativ-Prompt oder Audio unterstützt, und GET /v1/models liefert die vollständige Modellliste mit Preisen. Bau deine UI aus diesen beiden Antworten, und neue Engines tauchen von selbst auf. Die Spezifikation ist unter /openapi.json maschinenlesbar, und für Coding-Agents gibt es eine /llms.txt.

7. Schnittstellen für Agents: MCP und CLI

Immer öfter ruft nicht deine App deine Video-API auf, sondern ein Agent. Zwei Schnittstellen lohnen sich:

Ein Remote-MCP-Server. Der von eroq liegt unter https://eroq.ai/mcp, läuft über Streamable HTTP, wird mit demselben Bearer-Schlüssel authentifiziert und stellt generate_image, generate_video, get_video_status, generate_speech, enhance_prompt, list_models, list_voices, list_characters und get_account bereit. Er lässt sich in ChatGPT als benutzerdefinierter Connector einbinden, außerdem in Claude im Web und auf dem Desktop, in Cursor und in Codex CLI. Für Clients, die keine Header senden können, gibt es die Form /mcp/<key>: Dort ist die URL selbst das Geheimnis und sollte auch so behandelt werden. Die Einrichtung pro Client steht unter /docs/mcp.

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer $EROQ_API_KEY"

Eine CLI. Das Paket eroq läuft auf Node 18+ ganz ohne Abhängigkeiten: eroq login, eroq image "…", eroq video "…" -s 8 --aspect 9:16, eroq speech "…" -v aria. eroq mcp startet einen lokalen stdio-MCP-Server, der Medien in Dateien schreibt, und genau diese Form wollen Coding-Agents.

Zwei weitere Punkte, wenn die Grundlagen sitzen

Batch-Struktur. Wenn du Sequenzen statt Einzelstücke renderst, such nach einer Ressource, die die Sequenz abbildet. Die Ressource films von eroq speichert ein Storyboard, und POST /v1/films/{id}/render dreht jede Szene, rechnet pro Szene ab und hält sauber an, wenn ein Guthaben leer ist; siehe /docs/films.

Hosting des Outputs. Gerenderte URLs sind kein dauerhafter Speicher. Kopier sie entweder beim Erfolgs-Webhook in deinen eigenen Bucket, oder nutz den eroq Store unter /v1/storage/objects (2 Credits pro 10 MB) und behalte ein einziges führendes System.

Die Checkliste

1. Asynchroner Job mit einem List-Endpoint zur Wiederherstellung.
2. Signierte Webhooks, die URLs enthalten, keine Bytes.
3. Automatische Erstattung bei Fehlschlägen und keine Kosten für Ablehnungen durch die Richtlinie.
4. Freigabeprüfungen vor der Abbuchung und kein stiller Engine-Fallback.
5. Eine Abrechnungseinheit, die du einem Kunden nennen kannst.
6. Rate Limits pro Schlüssel, die mit dem Plan wachsen.
7. Discovery von Modellen, Preisen und Fähigkeiten zur Laufzeit.

Geh diese Liste bei jedem Anbieter durch, auch bei diesem. Alles oben Genannte ist unter /docs dokumentiert und unter /pricing bepreist.

Häufige Fragen

Ist die Video-API von eroq synchron oder asynchron?

Asynchron. POST /v1/videos/generations liefert eine Job-ID zurück, und du pollst entweder den Job oder empfängst einen signierten video.generation.succeeded-Webhook. Ein List-Endpoint liefert die letzten Jobs des Workspace, sodass bei einem Neustart nie ein Render verloren geht.

Zahle ich, wenn ein Video-Render fehlschlägt?

Nein. Fehlgeschlagene Generierungen werden automatisch erstattet, und Requests, die die Inhaltsrichtlinie blockiert, liefern content_blocked ohne Kosten zurück. Plan-Freigaben und nicht verfügbare Engines werden geprüft, bevor sich auch nur ein Credit bewegt.

Kann ich die Video-API aus einem Agent heraus statt aus Code aufrufen?

Ja. Ein Remote-MCP-Server unter https://eroq.ai/mcp stellt ChatGPT, Claude, Cursor und Codex Tools für Generierung, Status und Konto bereit, und die eroq-CLI bringt einen lokalen stdio-MCP-Server mit, der Renders als Dateien speichert.

Hol dir einen API-Schlüssel und schick den ersten Job ab: /signup.