Kling 3.0 API: Migration, Motion Control und Code

Ein Kling-2.6-Request wird nicht dadurch zuverlässig zu Kling 3.0, dass du nur den Modell-String austauschst. Kling 3.0 ist offiziell verfügbar, doch V3, Turbo, Omni und Motion Control haben jeweils eigene Funktionen und Schemata. Für eine sichere Migration wählst du zuerst den passenden Endpunkt und ergänzt Audio, Multi-Shot- und Referenzsteuerung anschließend schrittweise.

Den passenden Endpunkt vor dem Coding festlegen

In der offiziellen VIDEO-3.0-Dokumentation beschreibt Kling 3.0 als Nachfolger von VIDEO 2.6 und VIDEO O1: VIDEO 2.6 wird zu VIDEO 3.0 weiterentwickelt, VIDEO O1 zu VIDEO 3.0 Omni. In der Developer API gibt es getrennte, modellspezifische Operationen. „Kling 3.0 API“ steht also für eine Modellfamilie mit mehreren Zugriffswegen, nicht für einen universellen Request-Body.

Ein häufiger Integrationsfehler besteht darin, das Komfortschema eines Providers mit Klings direktem Schema zu vermischen: Ein funktionierender Hosted-Request von Krea ist kein Beleg dafür, dass dieselbe URL oder dieselben Felder auch in der offiziellen Kling-Entwicklerdokumentation gelten.

Einen breiteren Überblick über die verfügbaren Wege bietet der Leitfaden zur Kling-API-Integration. Dieser Artikel konzentriert sich auf die Migration zu Kling 3.0 und das Verhalten der Endpunkte.

Was sich beim Wechsel von Kling 2.6 zu 3.0 verändert

Nach Klings eigener Modellübersicht liegt das wesentliche Upgrade bei Steuerbarkeit, Kontinuität und audiovisueller Regie – nicht einfach bei einer höheren Auflösungsvorgabe. Die folgende Tabelle basiert auf den Funktionen, die Kling dieser Modellfamilie zuschreibt.

In der Praxis kann aus einer 2.6-Integration mit einem einzelnen kurzen Prompt in 3.0 eine gezielt inszenierte Sequenz werden. Kling verweist außerdem auf eine bessere Erhaltung von Charakteren, Objekten und Szenendetails bei Kamerabewegungen, veröffentlicht dafür aber keinen unabhängigen Konsistenz-Benchmark. Trenne diese Aussage daher von dem, was deine Anwendung tatsächlich testen kann.

Eine minimale asynchrone Krea-Integration aufsetzen

Videogenerierung läuft asynchron ab. Deine Anwendung sollte einen Job absenden, dessen Task-ID speichern, den Status abfragen oder einen Callback empfangen und das fertige Ergebnis dauerhaft ablegen. Halte den ursprünglichen HTTP-Request nicht offen, während das Modell rendert.

Das folgende Beispiel verwendet den öffentlich dokumentierten Kling-3.0-Endpunkt von Krea, weil Request- und Job-Felder im veröffentlichten Kling 3.0 API guide einsehbar sind. Ersetze provider-spezifische URL und Feldnamen erst, nachdem du das offizielle Kling-Schema geprüft hast, das du einsetzen möchtest.

Job für die Generierung absenden

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

In Kreas dokumentierter Antwort stehen eine job_id und ein anfänglicher Status wie scheduled. Für Statusprüfungen nutzt das Provider-Beispiel einen separaten Endpoint zur Job-Abfrage. Speichere die Job-ID zusammen mit deiner eigenen Bestell-ID in der Datenbank, bevor das Polling beginnt.

Mit Timeout pollen und Ergebnis speichern

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

In Kreas Beispielen dauerten Generierungen 51 Sekunden beziehungsweise 2 Minuten und 3 Sekunden. Nutze deshalb queue-taugliche Timeouts, statt eine feste Kling-Generierungszeit zu versprechen.

Im Produktivbetrieb kann ein Webhook wiederholtes Polling ersetzen. Prüfe die Job-ID gegen einen Job, den dein System selbst angelegt hat, gestalte den Handler idempotent und behandle einen nicht signierten Callback nicht allein als Identitätsnachweis.

3.0-Steuerungen schrittweise ergänzen

Die Parameternamen unterscheiden sich zwischen der direkten Kling API und Hosted-Providern. Statt provider-spezifisches JSON über die gesamte Anwendung zu verteilen, solltest du eine kleine Kompatibilitätsschicht bauen.

Der offizielle Leitfaden unterstützt natives Audio, Elementreferenzen, Multi-Shot-Erzählungen und Dialoge in fünf benannten Sprachen. Der von dir gewählte API-Endpunkt kann jedoch nur einen Teil dieser Funktionen auf Familienebene anbieten.

Ein eigenes Multi-Shot-Payload

Kreas dokumentiertes Schema verwendet zeitlich definierte multi_prompt-Abschnitte. Für eine Hosted-Integration ist das ein nützliches Muster:

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Validiere, dass die Dauer auf oberster Ebene der Summe aller Abschnittsdauern entspricht. Krea meldet für einen Test mit drei Abschnitten und 12 Sekunden eine Ausgabe von 12,04 Sekunden. Gehe also nicht davon aus, dass die Dateidauer millisekundengenau dem mathematischen Wert entspricht.

Jeder Krea-Abschnitt ist auf 512 Zeichen begrenzt, die gesamte inszenierte Sequenz auf 15 Sekunden. Formuliere jeden Abschnitt als Shot-Anweisung – Subjekt, Veränderung und Kamera – statt als lange Szenenbeschreibung. Verwendet dein direkter Kling-Endpunkt stattdessen die offizielle Shot-Grammatik, behältst du dasselbe Zeitachsenmodell bei und übersetzt das Payload an der Adapter-Grenze.

Vorgaben für Audio und Sprache

Der offizielle Leitfaden nennt Chinesisch, Englisch, Japanisch, Koreanisch und Spanisch als unterstützte Dialogsprachen. Außerdem beschreibt er Dialekte, Akzente, charakterspezifische Dialoge und gemischtsprachige Szenen. Nicht unterstützte Dialogeingaben werden laut Dokumentation ins Englische übersetzt. Mehrsprachige Anwendungen sollten daher nicht davon ausgehen, dass jede Ausgangssprache unverändert erhalten bleibt.

Audio ist auch eine Kostenfrage. Kreas veröffentlichte Preise nennen für std $0.1764 pro Sekunde ohne Audio und $0.2646 mit Audio; bei pro sind es $0.2352 ohne Audio und $0.3528 mit Audio. Der angegebene 4K-Preis liegt bei $0.441 pro Sekunde, unabhängig davon, ob Audio enthalten ist. Das sind Krea-Preise, kein allgemeingültiger Kling-API-Tarif.

Ein sinnvoller Iterationsablauf: zunächst stumme Entwürfe rendern und Audio erst für den finalen std- oder pro-Kandidaten aktivieren.

Produktivbetrieb: Kosten, Geschwindigkeit und Fehlerfälle

Im offiziellen Consumer-Leitfaden von Kling kostet VIDEO 3.0 6 Credits pro Sekunde für 720p ohne natives Audio, 8 Credits pro Sekunde für 1080p ohne natives Audio, 9 Credits pro Sekunde für 720p mit Audio und 12 Credits pro Sekunde für 1080p mit Audio. Voice Control kostet zusätzlich 2 Credits pro Sekunde. Diese Werte erklären die relativen Kosten innerhalb dieses Leitfadens; ohne Prüfung der aktuellen Developer-Preisseite solltest du sie nicht in einen Dollarpreis für die Developer API umrechnen.

Die Entscheidung lautet nicht einfach: „Welches Modell ist am günstigsten?“ Sie betrifft Abrechnung und Betrieb:

Behandle Fehler nach Kategorie:

1. Wiederhole vorübergehende Provider-Fehler mit begrenztem exponentiellem Backoff.
2. Wiederhole ungültige Parameter nicht, bevor dein Adapter das Payload korrigiert hat.
3. Nutze einen clientseitigen Idempotency-Key oder eine Bestell-ID, damit ein Netzwerk-Timeout keinen unbemerkten doppelten Job erzeugt.
4. Setze für Batch-Generierungen eine harte Obergrenze in Dollar oder Credits.
5. Lade das Ergebnis herunter oder kopiere es in dauerhaften Storage, bevor die temporäre Provider-URL abläuft.
6. Logge Modellvariante, Dauer, Audio-Einstellung, Auflösungsstufe und Provider gemeinsam; für die Kostenrechnung reicht „Kling 3.0“ allein nicht aus.

Checkliste für die Migration von Kling 2.6 zu 3.0

1. Bestehende 2.6-Aufrufe erfassen. Dokumentiere Modell-IDs, Bildeingaben, Start-/Endframes, Dauer, Audio und Callback-Verhalten.
2. Den passenden Weg der 3.0-Familie wählen. Nutze V3 für filmische Prompt-basierte Generierung, Turbo für den schnelleren Weg, Omni für den multimodalen O1-artigen Pfad und Motion Control für Arbeit mit Bewegungsreferenzen.
3. Einen Provider-Adapter erstellen. Kapsle die Schemata von direktem Kling, Krea und anderen Hosted-Anbietern hinter getrennten Übersetzern.
4. Zuerst den kleinsten Request migrieren. Teste eine stumme Generierung mit fünf Sekunden und 16:9, bevor du Audio oder Multi-Shot-Steuerungen ergänzst.
5. Pro Test nur eine Steuerung hinzufügen. Prüfe erst die Dauer, dann Audio, anschließend Shot-Regie und danach Referenzen. So lässt sich ein fehlerhaftes Feld leichter isolieren.
6. Terminalzustände testen. Decke Erfolg, Fehler, Abbruch, Timeout, doppelten Callback und abgelaufene Output-URL ab.
7. Einen kostenbewerteten Shadow Launch durchführen. Vergleiche einen festen Prompt-Satz über 2.6 und 3.0 mit gleicher Dauer und Ausgabestufe. Entscheide danach, ob Qualitäts- oder Steuerungsgewinn den neuen Weg rechtfertigen.

Die Migration ist abgeschlossen, wenn deine Anwendung auf die bisherige Modell-ID zurückwechseln kann, ohne Geschäftslogik, Abrechnungsregeln oder Ergebnisverarbeitung anzupassen.

Kling 3.0 API: Häufige Fragen

Gibt es eine offizielle Kling 3.0 API?

Ja. Die offizielle Entwicklerdokumentation von Kling enthält modellspezifische API-Seiten für 3.0, und Klings eigener Leitfaden dokumentiert VIDEO 3.0 als Nachfolger von VIDEO 2.6. Das exakte Endpunktschema solltest du in der aktuellen Developer Console prüfen, da einige Seiten clientseitig gerendert werden.

Ist Motion Control ein Kling-3.0-Parameter?

Davon solltest du nicht ausgehen. Motion Control ist eine spezialisierte Funktion mit eigener Modellseite im Kling-Ökosystem. Verwende die Operation und das Eingabeschema, die dein gewählter Provider dokumentiert, statt ein ungeprüftes Feld motion_control an einen Standard-Text-zu-Video-Request anzuhängen.

Wie lange können Kling VIDEO 3.0 Videos sein?

Nach Klings offizieller Modellübersicht unterstützt VIDEO 3.0 flexible Ausgaben von 3 bis 15 Sekunden. Ein bestimmter Hosted- oder Turbo-Endpunkt kann engere Grenzen setzen, daher solltest du den ausgewählten Endpunkt validieren.

Unterstützt Kling 3.0 natives Audio?

Ja, laut offiziellem VIDEO-3.0-Leitfaden. Dort werden charakterspezifische Dialoge, mehrere Sprachen, Dialekte und Akzente beschrieben. Ob Audio optional ist und wie es abgerechnet wird, hängt jedoch vom jeweiligen Endpunkt oder Provider-Schema ab.

Ist Kling 3.0 Omni dasselbe wie normales Kling 3.0?

Nein. Kling positioniert VIDEO 3.0 als Nachfolger von 2.6 und VIDEO 3.0 Omni als Nachfolger von O1. Provider-Seiten können beide unter unterschiedlichen Modell-IDs sowie mit abweichenden Referenz- oder Sprachsteuerungen anbieten.

Kann ein Kling-Webabo API-Aufrufe bezahlen?

Behandle Consumer-Abonnements und die Abrechnung der Developer API als getrennt, bis die aktuelle Account-Dokumentation etwas anderes sagt. Für den API-Weg sind normalerweise ein eigenes Entwicklerkonto, ein eigener Key und eine separate Abrechnungseinrichtung erforderlich.

Die sinnvolle Migrationsgrenze ist einfach: Behalte den Job-Lebenszyklus der 2.6-Integration bei, ersetze den modellspezifischen Adapter und prüfe jede neue 3.0-Steuerung gegen den Endpunkt, der sie tatsächlich bereitstellt. So vermeidest du die teuerste Fehlerklasse: eine Integration, die zwar erfolgreich absendet, aber unbemerkt die falsche Variante, den falschen Audiomodus oder die falsche Abrechnungsstufe nutzt.