So rufen Sie die Kling 2.5 Turbo Text-zu-Video-API auf: curl- und Python-Anleitung

Was der kling-2.5-turbo/text-to-video-Endpunkt für Sie bereitstellt

kling-2.5-turbo/text-to-video ist ein Text-zu-Video-Modell, das auf HiAPI öffentlich bereitgestellt wird. Sie geben ihm einen Text-Prompt, und es liefert ein generiertes Video zurück. Das „turbo“ im Namen verrät, worauf es optimiert ist: eine schnellere Durchlaufzeit als die Standard-Qualitätsstufe, auf Kosten einiger Details. Für Entwurfs-Renderings, Storyboard-Vorschauen, Social-Media-Clips und kreative Iteration ist dieser Kompromiss meist die richtige Wahl.

Das Wichtigste, das Sie sich vor der ersten Codezeile einprägen sollten: Dies ist ein asynchroner Endpunkt. Die Videogenerierung dauert Sekunden bis Minuten, weit über jedes vernünftige HTTP-Timeout hinaus. Deshalb ist die API in zwei Operationen aufgeteilt:

1. Absenden – Sie senden Prompt und Parameter per POST und erhalten sofort eine Aufgabenkennung zurück.
2. Polling – Sie rufen die Aufgabe wiederholt per GET mit dieser Kennung ab, bis sie einen Endzustand erreicht, und lesen dann das Videoergebnis aus der abgeschlossenen Antwortnutzlast.

Wenn Sie versuchen, dies als einzelnen blockierenden Aufruf zu modellieren, stoßen Sie auf Timeouts, doppelte Generierungen bei Wiederholungen und Verbindungsabbrüche unter hoher Last. Das Muster „erst absenden, dann abfragen“ ist kein Hindernis, das umgangen werden muss; es ist das korrekte mentale Modell. Jedes Codebeispiel unten baut darauf auf, und sobald Sie das verinnerlicht haben, ist der Rest der Integration unkompliziert.

Eine weitere Erwartung sollten Sie von Anfang an setzen: Der Endpunkt ist zustandsbehaftet, aber der Zustand liegt serverseitig, nicht bei Ihnen. Aufgaben existieren unabhängig von Ihrer HTTP-Verbindung. Ihr Skript kann mitten im Polling abstürzen, neu gestartet werden und mit der ID wieder an dieselbe Aufgabe anknüpfen – vorausgesetzt, Sie haben diese ID irgendwo persistent gespeichert. Entwerfen Sie von Anfang an mit diesem Gedanken.

Anfragestruktur: Prompt, Schnell-Preset und flexible Dauer

Sie steuern nur wenige Felder, aber jedes Feld wirkt sich substanziell auf die Aufgabe aus. Folgendes zählt wirklich.

Prompt

Der Prompt ist die wichtigste kreative Eingabe. Behandeln Sie ihn als Szenenbeschreibung, nicht als Suchanfrage. Gute Prompts für dieses Modell enthalten typischerweise:

• Subjekt – wer oder was auf dem Bildschirm zu sehen ist.
• Aktion – was das Subjekt im Clip tut.
• Kamera – Bildkomposition und Bewegung, z. B. slow dolly in, static wide shot, handheld follow.
• Umgebung und Licht – Szene, Tageszeit, Stimmung.
• Stil – wenn Sie die Anmutung lenken wollen, z. B. cinematic, anime, product photography.

Bleiben Sie konkret und stellen Sie das Subjekt an den Anfang. Vage Prompts erzeugen vage Bewegungen, und die Turbo-Stufe verstärkt dies, weil sie weniger Interpretationsspielraum lässt.

fast/turbo-Preset

Die Modellfamilie unterstützt ein Schnell-Preset, das einen Teil der Detailtreue gegen Latenz eintauscht. Wenn Sie es aktivieren, teilen Sie dem Backend mit, Geschwindigkeit zu priorisieren – die Bewegung bleibt stimmig, aber feine Texturen, kleine Gesichter und komplexe Hintergründe verschlechtern sich früher als auf dem Qualitätspfad. Verwenden Sie es in Ihren Iterationsschleifen beim Testen von Prompt-Varianten; wenn Sie schließlich die Hauptaufnahme rendern, überlegen Sie, ob der Qualitätspfad der bessere letzte Schritt ist. Das Preset ist ein Anforderungsfeld und damit eine Entscheidung pro Aufgabe, keine globale kontoweite Einstellung.

Flexible Dauer

Die Dauer ist innerhalb des vom Modell unterstützten Bereichs flexibel, nicht auf eine einzige Länge festgelegt. Eine längere Dauer bedeutet mehr zu generierende Frames, also längere Fertigstellungszeit und höhere Kosten – die Abrechnung erfolgt nach Ausgabesekunden. Wählen Sie die kürzeste Dauer, die die Aufnahme erfüllt. Eine Fünf-Sekunden-Schleife für einen Social-Media-Post braucht nicht dieselbe Länge wie ein narratives Element.

Felddisziplin

Setzen Sie nur die Felder, die Sie brauchen. Unbekannte oder falsch geschriebene Schlüssel sind eine häufige Quelle stiller Fehlkonfigurationen, halten Sie den JSON-Anfragetext also klein, eindeutig und zusammen mit dem Rest Ihrer Pipeline-Konfiguration versioniert.

Anfrage mit curl senden

Jeder HiAPI-Aufruf verwendet dasselbe Authentifizierungsmuster: einen Bearer-Token im Header Authorization. Legen Sie den Schlüssel in einer Umgebungsvariable ab, damit er nicht in der Shell-Historie oder in committeten Skripten auftaucht.

export HIAPI_API_KEY="your_api_key_here"

Senden Sie dann die Aufgabe ab. Die genauen Feldnamen und der Endpunktpfad sollten der Modellreferenz entnommen werden; die folgende Form ist die kanonische Form:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "prompt": "A slow dolly-in on a ceramic coffee cup on a wooden table, morning light raking across the surface, steam rising, shallow depth of field, cinematic",
    "duration": 5,
    "fast": true
  }'

Erwarten Sie kein Video zurück. Sondern eine Bestätigung mit der Aufgabenkennung und ihrem Anfangszustand – meist Status queued oder processing plus ein Feld id. Speichern Sie diese ID; sie ist das Handle für alle nachfolgenden Operationen.

Die minimale Antwort sieht ungefähr so aus:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "kling-2.5-turbo/text-to-video"
}

Der Absendeaufruf sollte schnell zurückkehren – unter normalen Bedingungen deutlich unter einer Sekunde. Wenn er hängt, liegt das Problem an der Verbindung oder der Authentifizierung, nicht am Modell. Bei 401 prüfen Sie das Header-Format (das Präfix Bearer ist wichtig). Bei 422 ist Ihr JSON-Anfragetext fehlerhaft oder es fehlen Pflichtfelder.

Fügen Sie diesem Aufruf kein -L, keine Wiederholungsversuche und kein langes Timeout hinzu. Der Absendeschritt gelingt entweder schnell oder scheitert schnell. Das gesamte Warten findet in der Polling-Schleife statt, um die es als Nächstes geht.

Dieselbe Anfrage in Python

Die Python-Version ist eine dünne Hülle um denselben HTTP-Vertrag. Verwenden Sie requests mit einer gemeinsamen Session, damit das Verbindungspooling zwischen Absenden und jedem Polling greift. Kapseln Sie es in Funktionen, damit der Rest Ihres Codes nie direkt mit rohem HTTP in Berührung kommt.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

session = requests.Session()

def submit_video(prompt: str, duration: int = 5, fast: bool = True) -> str:
    body = {
        "model": "kling-2.5-turbo/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "fast": fast,
    }
    resp = session.post(f"{BASE}/video/generations", json=body, headers=HEADERS, timeout=15)
    resp.raise_for_status()
    return resp.json()["id"]

def poll_video(job_id: str, timeout_s: int = 600, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = session.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed", "cancelled"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    job = submit_video("A slow dolly-in on a ceramic coffee cup, morning light, steam rising, cinematic")
    result = poll_video(job)
    print(result)

Einige Details sollten Sie beibehalten statt wegzukürzen: timeout bei jeder Anfrage, damit ein hängender Socket Ihren Worker nicht blockiert; exponentielles Backoff mit einer vernünftigen Obergrenze; und ein separater TimeoutError, damit der Aufrufer zwischen „läuft noch“ und „kaputt“ unterscheiden kann.

Wenn Sie httpx bevorzugen, ist die Umstellung unkompliziert – gleiche Methoden, URLs und JSON-Anfragetexte. Die Transportschicht ist nicht der interessante Teil; der Vertrag ist es. Speichern Sie die job_id an einem persistenten Ort, bevor Sie mit dem Polling beginnen, damit ein Neustart eine laufende Generierung nicht verwaisen lässt.

Aufgaben abfragen und Antworten lesen

Die Polling-Schleife ist der Ort, an dem die meisten Integrationsfehler auftreten. Drei Regeln halten sie zuverlässig.

Regel 1: Nur Endzustände beenden die Schleife

Sie sehen Übergangszustände – queued, processing – und Endzustände wie succeeded, failed und cancelled. Nur Endzustände verlassen die Schleife. Behandeln Sie unbekannte Statusstrings nicht als Erfolg, und brechen Sie nicht bei processing ab. Protokollieren Sie den Status bei jeder Iteration; wenn um zwei Uhr nachts etwas schiefgeht, ist dieses Log Ihr einziger Beweis.

Regel 2: Backoff statt Leerlauf

Für eine Aufgabe, die eine Minute dauert, ist festes Ein-Sekunden-Polling verschwenderisch; bei Batch-Aufgaben kann aggressives Polling an Ratenlimits stoßen. Beginnen Sie bei etwa zwei bis drei Sekunden, multiplizieren Sie pro Runde mit etwa 1,5 und begrenzen Sie auf zehn bis fünfzehn Sekunden. Die Gesamtzahl der Anfragen für eine einminütige Aufgabe sinkt von sechzig auf unter fünfzehn, während die Erkennungslatenz im schlimmsten Fall nur der Obergrenze entspricht.

Regel 3: Assets und Metadaten trennen

Die abgeschlossene Antwortnutzlast enthält beides. Das Video selbst wird als URL geliefert (oft mit Ablaufzeit), und alles andere – Aufgaben-ID, Modell, Dauer, Status, Laufzeit – sind Metadaten darüber, wie Sie es erhalten haben. Lesen Sie die URL, laden Sie sie rechtzeitig herunter und speichern Sie selbst. Generierte Asset-URLs sind kein permanentes CDN; behandeln Sie sie als Übergabe, nicht als Zuhause. Speichern Sie die Aufgaben-ID zusammen mit Ihrer eigenen Kopie, damit Sie jeden Clip bis zur genauen Anfrage zurückverfolgen können, die ihn erzeugt hat.

Hinweis zu failed

Der Status failed ist ein aufgabenbezogenes Ergebnis, kein Transportfehler. Der HTTP-Aufruf war erfolgreich; die Generierung war es nicht. Lesen Sie die Fehlernutzlast – sie kann auf eine Ablehnung durch die Inhaltsrichtlinie, eine nicht unterstützte Parameterkombination oder einen internen Fehler hindeuten. Eine Richtlinienablehnung unverändert erneut zu versuchen, wird nur wieder scheitern, also verzweigen Sie nach Ursache, bevor Sie einen Wiederholungsversuch erwägen.

Fehler, Timeouts und Wiederholungsversuche behandeln

Unterscheiden Sie zwei Fehlerwelten und behandeln Sie sie getrennt.

Transportfehler sind HTTP-Fehler: Verbindungsabbrüche, 5xx-Antworten, Ratenlimits 429 und Client-Timeouts. Diese sagen nichts darüber aus, ob die Aufgabe gelaufen ist. Wiederholen Sie mit exponentiellem Backoff und Jitter und begrenzen Sie die Anzahl der Versuche.

Aufgabenfehler sind Endzustände in erfolgreichen HTTP-Antworten. Die Aufgabe lief und hat ein eindeutiges Ergebnis erzeugt. Das erneute Ausführen des Pollings hilft nicht; wenn Sie wiederholen, ist das ein neues Absenden, und nur dann, wenn die Fehlerursache vorübergehend war.

Das Richtige wiederholen

Hier liegt die Feinheit. Wenn Ihr Absendeaufruf ein Timeout hat, wissen Sie nicht, ob der Server die Aufgabe angenommen hat. Ein blindes erneutes Absenden kann zwei Generierungen und zwei Abbuchungen erzeugen. Ein sichereres Muster ist, das Absenden mit einem clientgenerierten Anforderungsschlüssel idempotent zu machen, den Sie als Header oder Anfragetextfeld senden, sodass ein doppeltes Absenden die ursprüngliche Aufgabe zurückgibt statt eine neue zu starten. Bietet die von Ihnen genutzte API-Oberfläche dies nicht, protokollieren Sie bei einem Timeout beim Absenden den Prompt-Hash und die Dauer und prüfen Sie Ihre letzten Aufgaben, bevor Sie erneut absenden.

Timeouts auf jeder Ebene

Legen Sie drei verschiedene Timeouts fest und werfen Sie sie nicht in einen Topf:

• Timeout pro Anfrage – kurz, z. B. zehn bis fünfzehn Sekunden. Dies begrenzt den einzelnen HTTP-Aufruf, nicht die Aufgabe.
• Gesamtdeadline der Aufgabe – das Wanduhr-Budget für die gesamte Generierung. Wird es überschritten, markieren Sie die Aufgabe als verwaist, schlagen Alarm und machen weiter.
• Clientseitiges Timeout – wenn ein Benutzer wartet, entscheiden Sie, ob Sie den Fortschritt streamen oder dem Frontend das Aufgaben-Handle zurückgeben.

Praktische Wiederholungsstrategie

Wiederholen Sie 429 und 5xx mit Backoff, mit kleiner Obergrenze. Wiederholen Sie niemals 400, 401, 403 oder 422 – das sind Fehler in Ihrer Anfrage, und ihre Wiederholung verbrennt nur Kontingent. Protokollieren Sie den Antworttext jedes Fehlschlags; HiAPI-Fehlernutzlasten benennen in der Regel das fehlerhafte Feld.

Batch-Sicherheit

Beim Ausfächern vieler Aufgaben fügen Sie ein Nebenläufigkeitslimit und Startverzögerungen mit Jitter hinzu. Hundert gleichzeitige Absendungen sind ein selbstverschuldeter Ratenlimit-Vorfall. Ein Pool von fünf bis zehn Workern, die jeweils unabhängig pollen, ist deutlich stabiler und leichter zu beobachten.

Produktions-Checkliste vor dem Go-live

Bevor dies den Laptop verlässt, legen Sie diese Entscheidungen fest.

• Timeouts und Deadlines. Jeder Aufruf hat ein Timeout pro Anfrage, es gibt eine Gesamtdeadline der Aufgabe und eine klare Strategie, was passiert, wenn eine Aufgabe verwaist. Schreiben Sie sie als Konstanten, nicht als magische Zahlen.
• ID-Persistenz. Speichern Sie job_id und Prompt-Hash, bevor das Polling beginnt. Das ist der Schlüssel, der Neustarts und Audits möglich macht.
• Asset-Speicherung. Laden Sie das fertige Video bei Erfolg in Ihren eigenen Bucket herunter. Schicken Sie niemals URLs, die Sie nicht kontrollieren, als permanente Referenz an Frontend oder Datenbank.
• Protokollierung. Protokollieren Sie jeden Statusübergang mit Aufgaben-ID, Modell, Dauer, Preset und Laufzeit. Wenn Kosten- oder Qualitätsfragen auftauchen, ist dies der Datensatz, der sie beantwortet.
• Kostenbewusstsein. Die Abrechnung erfolgt nach Ausgabesekunden, also ist die Dauer Ihr wichtigster Kostenhebel. Das Turbo-Preset hält die Latenz (und damit die Worker-Belegung) niedrig. Verfolgen Sie die pro Feature generierten Sekunden, damit Kosten Diskussionen auf echten Zahlen statt Vermutungen beruhen.
• Idempotenz. Verwenden Sie beim Absenden einen clientseitigen Anforderungsschlüssel und legen Sie Regeln fest, was ein sicheres erneutes Absenden ausmacht.
• Fehler-UX. Entscheiden Sie jetzt, was Benutzer bei einem aufgabenbezogenen Fehler sehen: Wiederholen-Schaltfläche, Fallback-Prompt oder reine Textnachricht. Stilles Leerlaufen ist die schlechteste Wahl.
• Prompt-Versionskontrolle. Halten Sie Prompts in der Konfiguration statt inline in Handlern, damit Sie die Ausgaben verschiedener Varianten ohne erneutes Deployment vergleichen können.

Der Endpunkt selbst ist klein – ein Absenden, ein Polling. Fast der gesamte Engineering-Aufwand steckt im Lebenszyklus darum herum, und genau dort entscheidet sich Produktionsqualität. Beginnen Sie mit der Modellreferenz für kling-2.5-turbo/text-to-video auf HiAPI und bauen Sie dann das hier beschriebene Gerüst darum herum.