Die Video-API von Kling ist keine synchrone Schnittstelle, die „eine Anfrage, ein Video“ zurückgibt. Stattdessen wird zuerst eine Aufgabe erstellt, dann der Status abgefragt und schließlich das Ergebnis heruntergeladen. Wer sie wie Chat Completions programmiert, bleibt meist schon im ersten Schritt hängen: Die Anfrage ist erfolgreich, aber es kommt kein Video zurück, nur ein Aufgabendatensatz.

Dieser Beitrag erklärt in der realen Reihenfolge der Einbindung die Schnittstellengenerationen, Authentifizierung, das Senden, Polling, Callbacks, Download, Idempotenz und Migration der Kling-API im Jahr 2026. Pfade und Felder können sich mit Versionen ändern; vor der Abstimmung ist die offizielle Dokumentation maßgeblich.

Hinweis: Kling ist eine Marke der jeweiligen Rechteinhaber. Dieser Beitrag dient der technischen Erläuterung und begründet keine Zugehörigkeit oder Vertretungsbeziehung zu den genannten Unternehmen.

1. Zuerst zwei Schnittstellengenerationen unterscheiden

Bei Kling existieren derzeit zwei Schnittstellenformen nebeneinander; ihre Vermischung ist eine häufige Fehlerquelle.

Die neue Schnittstelle legt die Modellversion in den Pfad, zum Beispiel POST /text-to-video/kling-3.0-turbo oder POST /text-to-video/kling-2.6. Der Request-Body benötigt kein model_name mehr; die Authentifizierung erfolgt über einen Bearer-Header mit API-Key, zurückgegeben werden data.id und data.status.

Die alte Schnittstelle liegt meist unter /v1/videos/..., verwendet im Request-Body model_name zur Modellwahl, authentifiziert über ein mit AccessKey/SecretKey erzeugtes JWT und liefert task_id sowie task_status. Die alte Schnittstelle funktioniert weiterhin, für neue Projekte ist sie jedoch kein guter Ausgangspunkt.

Die Beispiele hier orientieren sich an der neuen Schnittstelle; am Ende steht eine Migrationscheckliste für beide Generationen.

2. Base URL und Authentifizierung

Die Kling-Dokumentation nennt unter anderem folgende Adressen:

  • https://api-singapore.klingai.com für Server außerhalb des chinesischen Festlands; laut Dokumentation ersetzt sie das alte api.klingai.com.
  • https://api-beijing.klingai.com als in Dokumentationsbeispielen auftauchende Beijing-Adresse für inländische Deployments.

Tatsächlich wählbare Regionen, Kontobereiche und Modellverfügbarkeit stehen in der Konsole. Nicht beliebig zwischen Regionen wechseln: Aufgaben und Ergebnisse gehören üblicherweise zur Region, in der sie erstellt wurden.

Der Authentifizierungsheader lautet Authorization: Bearer <API_KEY>, mit genau einem Leerzeichen zwischen Bearer und Key. Ein leicht übersehener Punkt: Auch GET-Abfragen der neuen Schnittstelle verlangen Content-Type: application/json.

Der Key gehört ausschließlich auf den Server. Browser, App oder Mini-Programm würden die Zugangsdaten offenlegen und zusätzlich an CORS- und nicht erreichbaren Callback-Problemen scheitern. Empfohlen ist, Aufgaben zentral vom Backend senden zu lassen; das Frontend erhält nur den Aufgabenstatus.

3. Die erste Videoaufgabe senden

Zuerst mit kürzester Dauer und niedrigster Auflösung die Kette testen, dann Parameter schrittweise ergänzen.

export KLING_API_KEY="ihr-schluessel"
export KLING_BASE_URL="https://api-singapore.klingai.com"

curl -sS -X POST "$KLING_BASE_URL/text-to-video/kling-3.0-turbo" \
  -H "Authorization: Bearer $KLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Stadtstraße nach dem Regen, langsame Kamerafahrt, filmisch, 16:9",
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "duration": 5
    },
    "options": {
      "external_task_id": "demo-20261019-001",
      "callback_url": "https://example.com/kling/callback"
    }
  }'

Der Geschäftscode einer erfolgreichen Antwort ist 0, die Aufgaben-ID steht in data.id, der Anfangszustand ist meist submitted:

{
  "code": 0,
  "message": "",
  "request_id": "…",
  "data": {
    "id": "…",
    "status": "submitted",
    "create_time": 0,
    "update_time": 0,
    "external_id": "demo-20261019-001"
  }
}

Bei den Parametern gibt es Grenzen: duration unterstützt bei 3.0 Turbo 3 bis 15 Sekunden, Standard sind 5 Sekunden; bei 2.6 sind 5 oder 10 Sekunden üblich; prompt ist auf etwa 3072 Zeichen begrenzt, offiziell werden höchstens 2500 empfohlen. Auflösung, Seitenverhältnis und Audiofähigkeit unterscheiden sich je Modell; Parameter nicht ungeprüft von einem Modell auf ein anderes übertragen.

4. Aufgabenstatus abfragen

Nach Erhalt der Aufgaben-ID über die Abfrageschnittstelle pollen:

GET /tasks?task_ids=<Aufgaben-ID>
GET /tasks?external_task_ids=<eigene-ID>

task_ids und external_task_ids schließen sich aus; mehrere IDs werden durch Kommas getrennt. data in der Antwort ist ein Aufgabenarray; jede Aufgabe enthält id, status, message, create_time, update_time, external_id, outputs und billing.

Es gibt vier Zustände:

  • submitted: angenommen, noch nicht gestartet.
  • processing: wird generiert.
  • succeeded: erfolgreich, outputs kann gelesen werden.
  • failed: fehlgeschlagen, message und Prüfungsgrund ansehen.

Beim Polling nicht mit fester hoher Frequenz anfragen. Empfohlen sind 5 Sekunden als Start, dann schrittweises Backoff auf 15 bis 30 Sekunden sowie ein Gesamt-Timeout. Videoaufgaben können in der Warteschlange stehen; bei Überschreitung zuerst Parallelität und Ressourcenpaket prüfen, statt sofort erneut zu senden.

Für Abgleich oder Nachladen die Cursor-Abfrage POST /tasks verwenden, filterbar nach start_time, end_time, status und product_type, maximal 500 Einträge pro Seite.

5. Callback und Signaturprüfung

Beim Senden einer Aufgabe callback_url mitgeben; die Plattform benachrichtigt bei Statusänderungen. Callbacks sparen Ressourcen gegenüber Polling, verlangen aber eine öffentlich erreichbare Schnittstelle, eine schnelle 200-Antwort und die eigentliche Verarbeitung in einer Queue.

Der Callback-Body enthält bei der neuen Schnittstelle id, status, message, outputs, external_id und billing; die alte Schnittstelle liefert task_id, task_status, task_result, wobei der Erfolgsstatus succeed geschrieben wird. Für beide Formate keine gemeinsame Parsing-Logik verwenden.

Zur Sicherheit lässt sich in der Konsole ein Webhook Secret (Beginn whsec_) anlegen. Der Callback trägt die Header webhook-id, webhook-timestamp und webhook-signature; signiert wird {webhook-id}.{webhook-timestamp}.{rawBody} mit HMAC-SHA256, das Ergebnis Base64-kodiert. Drei Prüfpunkte: Der Zeitstempel sollte innerhalb von plus/minus 5 Minuten liegen, die Signatur über den unveränderten Request-Body berechnet werden und der Vergleich mit einer Funktion für konstante Laufzeit erfolgen. Offiziell können alter und neuer Secret innerhalb einer 7-tägigen Übergangsfrist parallel bestehen, was eine sanfte Rotation ermöglicht.

Callbacks können doppelt oder in falscher Reihenfolge eintreffen. Die Verarbeitung muss über die Aufgaben-ID idempotent sein und Zustände nur vorwärts bewegen; processing darf nicht wieder zu submitted werden.

6. Ergebnisse herunterladen und speichern

Das Video einer erfolgreichen Aufgabe steht im outputs-Array; der Eintrag mit type gleich video enthält url, watermark_url, duration und id. Die url ist ein Download-Link mit Hotlink-Schutz; die direkte Einbettung in Webseiten oder Drittsysteme kann abgelehnt werden.

Zwei harte Randbedingungen:

  • Ergebnislinks werden etwa 30 Tage nach der Generierung bereinigt und taugen nicht als dauerhafte CDN-Adresse.
  • Wegen des Hotlink-Schutzes sollte serverseitig heruntergeladen und in den eigenen Objektspeicher übertragen werden.

Empfohlener Ablauf: Nach Erfolg sofort herunterladen, Content-Type und Dateigröße prüfen, eine Prüfsumme berechnen, in den Objektspeicher schreiben und die eigene Adresse mit der Aufgaben-ID verknüpfen. Für die externe Verteilung eigene signierte URLs mit Ablaufzeit verwenden.

7. Idempotenz, Wiederholung und Parallelität

Der teuerste Fehler bei Videoaufgaben ist „nach Timeout erneut senden“. Ein Timeout bedeutet nicht, dass die Aufgabe nicht erstellt wurde; möglicherweise kam nur die Antwort nicht zurück.

external_task_id ist das wichtigste Idempotenzmittel: Vor dem Senden eine stabile ID erzeugen und speichern, nach einem Timeout mit GET /tasks?external_task_ids=... gegenprüfen und erst nach Bestätigung erneut senden. Innerhalb eines Kontos muss diese ID eindeutig sein. Keine zufällige UUID als Wiederholungsschlüssel verwenden, sonst entsteht bei jedem Versuch eine neue Aufgabe.

Zur Parallelität: Laut offizieller Dokumentation zählt nur das „Erstellen von Aufgaben“ in die Parallelität, Abfragen nicht. Die Plattform stellt nicht selbst in eine Warteschlange; übersteigt die Anfrage die Paket-Slots, kommt 1303. Alle API-Keys eines Kontos teilen denselben Parallelitätspool. Empfohlen ist exponentielles Backoff ab mindestens 1 Sekunde sowie eine Sendewarteschlange in der Anwendung, die freie Slots abwartet.

8. Häufige Fehler im Überblick

Geschäftscode HTTP Bedeutung Empfehlung
1002 401 Zugangsdaten ungültig Key, Region und Header prüfen
1103 403 Keine Schnittstellen- oder Modellberechtigung Konto und Paket für das Modell freischalten
1101 429 Rückstand bei Postpaid Aufladen und erneut versuchen
1102 429 Paket aufgebraucht oder abgelaufen Paket kaufen oder Abrechnungsart wechseln
1201 400 Ungültiger Parameterwert message lesen, Dauer, Verhältnis, Auflösung prüfen
1301 400 Inhaltsprüfung nicht bestanden Prompt oder Material ändern, nicht unverändert wiederholen
1302 429 Zu viele Anfragen Frequenz senken, exponentielles Backoff
1303 429 Parallelität überschritten In Warteschlange senden, Slot abwarten
1203 404 Ressource oder Modell nicht vorhanden Pfad und Modellversion prüfen
5002 500 Interner Dienst-Timeout Aufgaben-ID behalten, später abfragen statt erneut senden

Bei der Fehlersuche zuerst den HTTP-Status, dann den Geschäftscode und schließlich request_id betrachten. Alle drei im Log erfassen; das verkürzt die Diagnose beim Support erheblich.

9. Checkliste für die Migration von der alten Schnittstelle

  1. Authentifizierung von AccessKey/SecretKey-JWT auf API-Key-Bearer umstellen; die alte Schnittstelle behält JWT-Kompatibilität.
  2. Pfad von /v1/videos/... auf modellbasierte Formen wie /text-to-video/kling-3.0-turbo ändern.
  3. model_name aus dem Request-Body entfernen; das Modell ergibt sich aus dem Pfad.
  4. Rückgabefelder von task_id, task_status auf id, status umstellen.
  5. Erfolgsstatus von succeed auf succeeded ändern.
  6. Abfrage von einem GET-Pfad pro Aufgabe auf GET /tasks?task_ids=... umstellen.
  7. Ergebnisse von task_result.videos auf Einträge mit type=video in outputs umstellen.
  8. Callback-Parser für altes und neues Format trennen, um Feldverwechslungen zu vermeiden.
  9. Logik für die 30-Tage-Bereinigung und die Übertragung trotz Hotlink-Schutz ergänzen.
  10. Mit external_task_id Idempotenz herstellen und Fehlerübungen für Timeout, doppelte Callbacks und Prüfungsablehnung durchführen.

Für die Migration empfiehlt sich ein Parallelbetrieb: neue Schnittstelle mit einem Teil des Traffics testen, alte Schnittstelle als Rollback-Fenster behalten und erst abschalten, wenn Erfolgsrate, Laufzeit und Abrechnung den Erwartungen entsprechen.

10. Prüfpunkte bei der Einbindung über ein Gateway

Erfolgt der Zugang über das ZSQH AI Gateway, sind neben Key und Base URL folgende Punkte zu klären: Ist der Videokanal freigeschaltet, werden asynchrone Aufgaben unverändert durchgereicht, bleiben external_task_id und Callback erhalten, und wie werden Ergebnis-URLs ausgeliefert? Die OpenAI-kompatible Schnittstelle für Textmodelle ist nicht direkt für Videoaufgaben geeignet.

Zuerst die Modelle und Preise ansehen, dann registrieren und einen Test-Key erstellen. Mit einer 5-Sekunden-Aufgabe die Kette aus Senden, Abfragen und Download prüfen, bevor über den Produktionsverkehr entschieden wird.

Häufige Fragen

Ist die Kling-API synchron oder asynchron?

Asynchron. Das Senden liefert nur eine Aufgaben-ID; danach GET /tasks abfragen oder Callbacks empfangen und bei Erfolg das Video aus outputs laden.

Sollte die Base URL Singapur oder Beijing sein?

Das hängt vom Serverstandort, der Kontozugehörigkeit und der Modellverfügbarkeit ab. Die offizielle Dokumentation nennt beide Adressen; vor der Einbindung in der Konsole bestätigen und für Senden und Abfragen dieselbe Region verwenden.

Was tun, wenn eine Aufgabe dauerhaft auf processing bleibt?

Zuerst Parallelitäts-Slots und Ressourcenpaket prüfen, dann, ob die Aufgabe in der Warteschlange steht. Bei Überschreitung mit der Aufgaben-ID abfragen statt erneut senden; bei Bedarf den Support mit request_id kontaktieren.

Kann die Ergebnis-URL direkt auf einer Website oder in einem Mini-Programm verwendet werden?

Nicht empfohlen. Der Link hat Hotlink-Schutz und wird nach etwa 30 Tagen bereinigt. Serverseitig herunterladen, in den Objektspeicher übertragen und über eigene signierte URLs bereitstellen.

Entstehen bei Wiederholungen doppelte Kosten?

Das hängt vom Fehlergrund und den Abrechnungsregeln ab. Nach einer Prüfungsablehnung nicht unverändert wiederholen; nach einem Netzwerk-Timeout zuerst per external_task_id prüfen, ob die Aufgabe existiert. Vor dem Produktivstart die Abrechnungsdokumentation lesen und mit kleinen Aufgaben validieren.

Weiterlesen: