Kling 4.0 Bild-zu-Video-API: Request-Referenz und ein echter Lauf

Kling 4.0 Bild-zu-Video verwandelt ein Startbild in einen 3–30 Sekunden langen Clip mit synchroner Audiospur. Dieser Leitfaden enthält einen direkt auf hiapi nutzbaren Request, die vom API akzeptierten und abgelehnten Felder sowie die Ergebnisse eines echten Laufs. Sie benötigen einen API-Schlüssel aus der hiapi-Konsole; die Modell-ID lautet kling-4.0/image-to-video, die aktuellen Spezifikationen finden Sie auf der Modellseite.

Falls Sie noch Kling 3.0 verwenden: Die Kling 4.0 API-Übersicht wurde vor der Veröffentlichung geschrieben und beschreibt die Ankündigung; diese Seite hier ist die aktuell gültige Referenz.

Minimaler Request (curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "prompt": "Sie dreht den Kopf leicht zur Kamera, das Haar weht im Wind, die Kamera fährt langsam vorwärts, Meeresrauschen im Hintergrund",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

Die Antwort liefert sofort eine Task-ID:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Fragen Sie GET /v1/tasks/<taskId> ab, bis data.status den Wert success erreicht, und lesen Sie dann data.output[0].url.

Python: Senden und Abfragen

import os, time, requests

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

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 恰好一张首帧图
            "duration": duration,        # 整数，3-30
            "resolution": resolution,    # "720p" 或 "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

Laden Sie die zurückgegebene MP4-Datei sofort herunter. Die Ausgabe-URL enthält einen expireAt-Zeitstempel (in unserem Lauf etwa sieben Tage später) und wird auf einer temporären Domain gehostet; kopieren Sie sie daher in Ihren eigenen Speicher, statt sie direkt zu verlinken.

Vom API akzeptierte Felder

Wir haben den Endpunkt mit absichtlich ungültigen Werten geprüft (diese liefern HTTP 400 INVALID_REQUEST zurück und es wird kein Task erstellt):

Feld	Beobachtete Regel
image_urls	Pflichtarray, genau ein Element (zwei → maxItems: got 2, want 1)
duration	Ganzzahl, Minimum 3, Maximum 30. Strings wie "5" werden abgelehnt (got string, want integer)
resolution	720p oder 1080p
aspect_ratio	Optional: 16:9, 9:16, 1:1, 21:9. Laut Modellseite folgt die Bildkomposition bei Auslassung dem Quellbild
prompt	Bewegungsbeschreibung; wir haben Requests ohne dieses Feld nur in Validator-Tests gesendet, daher als empfohlenes Feld betrachten

Zwei Dinge gehen beim Migrieren von Code anderer Videomodelle leicht schief:

• Das Feld heißt image_urls, nicht image_url. Wenn Sie image_url senden, erhalten Sie sowohl „Pflichtfeld image_urls fehlt“ als auch „zusätzliches Attribut image_url nicht erlaubt“.
• Es gibt keinen Audio-Schalter. audio, generate_audio und sound werden alle als zusätzliche Attribute abgelehnt. Audio wird immer zusammen mit dem Bild erzeugt; steuern Sie es über den Prompt (im obigen Beispiel wird Meeresrauschen verlangt).

Unbekannte Felder werden abgelehnt statt ignoriert, sodass Tippfehler als 400 sichtbar werden und nicht als stillschweigend ignorierte Einstellung verschwinden.

Hinweise für den Produktivbetrieb

• Callbacks statt Polling bevorzugen. Die Clip-Generierung dauert mehrere Minuten; übergeben Sie daher beim Erstellen des Tasks callback (mit url und when: "final") und verarbeiten Sie das Ergebnis im Webhook; Polling nur als Fallback nutzen.
• Vor dem Bezahlen validieren. Da ungültige Eingaben 400 zurückgeben und keinen Task erstellen, prüfen Sie Dauer und Auflösung zuerst im eigenen Code; fehlerhafte Requests kosten nichts, korrekte Requests werden jedoch pro angeforderte Sekunde berechnet.
• Abrechnung pro Sekunde und abhängig von der Auflösung. Längere Clips und 1080p kosten mehr; prüfen Sie die aktuellen Tarife unter Preise, statt sich auf Zahlen aus Artikeln zu verlassen.
• Task-ID speichern. Wenn das Polling aufgrund eines temporären Netzwerkfehlers fehlschlägt, fragen Sie dieselbe ID erneut ab, statt neu zu senden, sonst wird ein zweiter Clip erstellt und berechnet.

Gemessener Lauf

Wir haben den obigen Request gesendet: ein vertikales Startbild, duration: 3, resolution: "720p", kein aspect_ratio.

• Beobachtete Statusfolge bei Abfrage etwa alle 10 Sekunden: handling → archiving → success.
• Gesamte reale Dauer: etwa 274 Sekunden für einen 3-Sekunden-Clip. handling machte davon etwa 255 Sekunden aus; planen Sie in Minuten statt Sekunden und richten Sie sich auf Callbacks aus.
• Ausgabedatei (mit ffprobe geprüft): H.264-Video, 1280×720, 3,04 Sekunden, plus eine AAC-Audiospur gleicher Länge. Der Ton ist also tatsächlich in die MP4 eingebettet, und die Bildkomposition folgt dem 16:9-Quellbild.

Wir haben nicht getestet: 1080p, Dauern über 3 Sekunden und vom Standard abweichende aspect_ratio-Werte. Diese Einschränkungen stammen aus API-Validierungsnachrichten und der Modellseite, nicht aus erzeugten Ausgaben.

Verwandte Seiten

• Modellseite für Kling 4.0 Bild-zu-Video
• Modellseite für Kling 4.0 Text-zu-Video, für Fälle ohne Quellbild
• Modellseite für Kling 3.0 Bild-zu-Video
• So verwenden Sie Kling 3.0 Turbo Bild-zu-Video
• hiapi-Preise
• hiapi-Dokumentation

Häufig gestellte Fragen

Kann ich bei Kling 4.0 Bild-zu-Video das Audio deaktivieren?

Nicht über ein Request-Feld. audio, generate_audio und sound werden alle vom Validator abgelehnt. Beschreiben Sie stattdessen im Prompt den gewünschten Ton (oder dass kein Ton gewünscht ist).

Wie viele Eingabebilder kann ich senden?

Eines. image_urls muss genau ein Startbild enthalten.

Wie lange dauert ein Request?

Unser 3-Sekunden-720p-Clip benötigte Ende-zu-Ende etwa 274 Sekunden. Verwenden Sie für Produktionslast Callbacks.

Wie lang darf ein Clip höchstens sein?

Das API akzeptiert duration bis maximal 30 (ganze Sekunden) und lehnt höhere Werte ab; wir selbst haben nur 3-Sekunden-Clips erzeugt.