Kling 3.0 Turbo Bild-zu-Video-API in Python: Schema, vollständige Skripte und Fehlerbehandlung

Das Schema von kling-3.0-turbo/image-to-video ist kompakt und strikt: eine öffentliche Bild-URL, ein erforderlicher Bewegungsprompt, eine ganzzahlige Dauer von 3 bis 15 Sekunden sowie eine Ausgabe in 720p oder 1080p. Diese Seite ist die versionsspezifische Referenz zum Validieren dieses Request-Bodys und zur Unterscheidung zwischen HTTP-400-Fehlern und asynchronen TASK_FAILED-Ergebnissen.

Für den allgemeinen Ablauf zum Erstellen, Polling, Callback und Herunterladen verwenden Sie den Kling-Python-Task-Runner und den Auswahlleitfaden für Omni/Turbo.

Turbo-Eingabeschema

Feld	Typ	Erforderlich	Zulässige Werte
prompt	string	Ja	Beschreibt Bewegung und Kameraführung
image_urls	Array von Strings	Ja	Genau eine öffentlich zugängliche Bild-URL
duration	integer	Nein	3 bis 15 Sekunden
resolution	string	Nein	720p oder 1080p

Turbo akzeptiert weder sound, aspect_ratio, negative_prompt, seed noch mode und ebenso wenig eine zweite Bild-URL. Das strikte Schema lehnt zusätzliche Eigenschaften ab, statt sie stillschweigend zu ignorieren.

Das Eingabebild bestimmt die Form des Bildes. Laden Sie es vor dem Erstellen des Tasks in einen öffentlichen Bucket oder ein CDN hoch; der Renderer kann localhost, private Dashboards und abgelaufene signierte URLs nicht abrufen.

Minimal funktionierender Request

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

Eine erfolgreiche Antwort enthält data.taskId. HTTP 200 bedeutet lediglich, dass die Erstellung erfolgreich war, nicht die Fertigstellung; das Video wird weiterhin asynchron gerendert.

Vorabvalidierung in Python

Validieren Sie die Einschränkungen vor dem Netzwerkaufruf, damit offensichtliche Fehler niemals einen Task erstellen:

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

Diese lokale Prüfung erkennt Formfehler der Werte, kann aber nicht belegen, dass das entfernte Bild öffentlich herunterladbar ist. Der Renderer führt diesen Abruf erst nach dem Erstellen des Tasks aus.

Vollständiges Python-Skript: Übermitteln, Polling, Herunterladen

Der obige Codeschnipsel endet bei der Task-ID. Diese Version führt den gesamten Job aus und speichert die MP4-Datei. Sie sendet den Header Idempotency-Key, sodass ein erneuter Versuch derselben Übermittlung nach einem Timeout den ursprünglichen Task zurückgibt, statt einen zweiten Task zu erstellen und zu berechnen:

import os
import time
import uuid

import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

Ein solcher 5-Sekunden-Clip in 720p kostet $0.65. Ersetzen Sie in der Produktion die Polling-Schleife durch ein oberes "callback": {"url": "https://your-app.example.com/hiapi/callback"} und deduplizieren Sie Benachrichtigungen anhand der Task-ID.

HTTP 400: Der Task wurde nie erstellt

Eine HTTP-400-Antwort ist das Ergebnis einer synchronen Schema-Validierung. Typische Ursachen sind:

Ungültige Eingabe	Warum sie fehlschlägt	Behebung
"duration": "5"	Ein String statt einer Ganzzahl wurde gesendet	Senden Sie stattdessen 5
"duration": 20	Der Maximalwert ist 15	Wählen Sie 3–15
Zwei image_urls	Turbo akzeptiert nur eine	Behalten Sie nur das Startbild
"resolution": "4K"	Turbo unterstützt 720p und 1080p	Verwenden Sie 720p oder 1080p oder wählen Sie Omni
"sound": true	sound ist nicht im Turbo-Schema enthalten	Entfernen Sie das Feld oder wählen Sie Omni
Fehlendes prompt	Turbo erfordert einen Prompt	Fügen Sie einen nicht leeren Bewegungsprompt hinzu

Da die Validierung vor der Erstellung fehlschlägt, gibt es keine Task-ID zum Polling. Protokollieren Sie den Antwort-Body und die Request-ID, korrigieren Sie den Request-Body und reichen Sie anschließend einen neuen Request ein.

TASK_FAILED: Erstellung erfolgreich, aber Rendering fehlgeschlagen

Wenn POST /v1/tasks HTTP 200 und eine Task-ID zurückgibt, handelt es sich bei einem späteren Fehler um ein Problem im asynchronen Task-Lebenszyklus, das getrennt von einem 400 behandelt werden sollte.

Häufige Ursachen sind:

• Die Bild-URL erfordert Cookies oder Autorisierungs-Header;
• Die signierte Bild-URL ist abgelaufen, bevor der Renderer sie abruft;
• Der Host blockiert serverseitige Abrufe oder leitet auf eine HTML-Seite weiter;
• Die Datei ist beschädigt oder ihr Medientyp stimmt nicht mit dem Inhalt überein;
• Der Anbieter kann dieses Rendering nicht abschließen.

Protokollieren Sie die Task-ID, den endgültigen Fehlercode und die Fehlermeldung, die ursprüngliche Eingabe-URL sowie den Zeitpunkt des Requests. Stellen Sie vor einem erneuten Versuch sicher, dass ein nicht authentifizierter Server das Bild mit einer 2xx-Antwort und einem Bild-Inhaltstyp abrufen kann. Ein blindes Wiederholen derselben nicht erreichbaren URL erzeugt nur einen weiteren fehlgeschlagenen Task.

Der allgemeine Python-Leitfaden enthält die gemeinsame Polling-Schleife für Endzustände und den Code zum Herunterladen der Ausgabe; wenn Sie ihn dort belassen, vermeiden Sie doppelte Lebenszykluslogik auf dieser Versionsreferenzseite.

Turbo-Preise und Modellauswahl

Die aktuellen Produktionspreise sind:

Turbo-Stufe	Preis pro Sekunde	5-Sekunden-Task
720p	$0.130	$0.65
1080p	$0.160	$0.80

Prüfen Sie vor der Nutzung in großem Umfang die Seite mit den aktuellen Preisen. Der Name Turbo beschreibt eine Modellvariante und verspricht weder, dass jede Auflösung günstiger ist, noch dass Tasks eine feste SLA für die Renderzeit einhalten.

Wenn Sie ein Endbild, Audio oder 4K benötigen, wählen Sie das Standard-Kling-3.0 (kling-3.0/image-to-video): Es akzeptiert ein oder zwei Bilder (Start- und Endbild), verfügt über einen sound-Schalter und kostet $0.10/s bei 720p ohne Audio bzw. $0.129/s bei 1080p ohne Audio. Wenn Sie Referenzbilder oder Referenzvideos benötigen, wählen Sie Omni. Für ein einzelnes Eingabebild in 720p oder 1080p sollten Sie diese Varianten mit Ihrem eigenen Bewegungsprompt benchmarken und Ausgabequalität, Wartezeit und Gesamtkosten bewerten.

Häufig gestellte Fragen

Wie viele Bilder akzeptiert Kling 3.0 Turbo Bild-zu-Video?

Genau eine öffentliche Bild-URL. Ein zweites Bild löst einen Schemafehler aus (image_urls: maxItems: got 2, want 1); wenn Sie Start- und Endbild steuern möchten, verwenden Sie Standard-Kling-3.0 Bild-zu-Video.

Welche Dauerwerte sind gültig?

Senden Sie eine Ganzzahl von 3 bis 15. Eine Zahl in Anführungszeichen wie "5" ist ein String und schlägt bei der Validierung fehl.

Unterstützt Turbo 4K oder Audio?

Kein 4K: Dieser Endpunkt akzeptiert 720p oder 1080p. Es gibt kein Feld sound, aber Turbo-Clips enthalten standardmäßig Audio, das nicht deaktiviert werden kann. Wenn Sie 4K oder eine stumme Ausgabe benötigen, verwenden Sie Standard-Kling-3.0 oder Omni.

Worin unterscheiden sich HTTP 400 und TASK_FAILED?

HTTP 400 bedeutet, dass der Request das Schema verletzt, sodass kein Task erstellt wurde. TASK_FAILED tritt nach einer gültigen Erstellungsantwort auf, in der Phase des Eingabeabrufs oder der Generierung.

Warum führt eine scheinbar öffentliche Bild-URL zu TASK_FAILED?

Die URL kann von Cookies abhängen, abgelaufen sein, serverseitige Abrufe blockieren oder HTML statt Bild-Bytes zurückgeben. Testen Sie sie vor einem erneuten Versuch ohne Browser-Authentifizierung.