Blog

Tutorial

So verwendest du kling-4.0-flash Bild-zu-Video über die HiAPI API: curl und Python

Praktische Anfrageübung: erste Frame-Bildeingabe, Polling asynchroner Aufgaben, synchrones Audio und Fehlerbehebung

Nov 12, 2026
Titelbild: Ein leicht versetzt gestapelter Stoß cremeweißer Papiere mit kohlschwarzen Rändern, dazwischen ein rostrotes Vorsatzblatt, darunter ein flacher Schatten.
Modell
kling-4.0-flash
Auf dieser Seite

Was der Endpunkt kling-4.0-flash Bild-zu-Video leistet

kling-4.0-flash/image-to-video ist ein bildkonditioniertes Videogenerierungsmodell. Du gibst ihm ein Bild – das erste Frame – zusammen mit einem Text-Prompt, und es liefert ein generiertes Video zurück, das mit diesem Frame beginnt und sich gemäß deiner Beschreibung entwickelt.

Das Wichtigste, das du dir vor dem Programmieren einprägen solltest: Dies ist kein Request/Response-Aufruf, der die Videodaten in derselben HTTP-Transaktion zurückgibt. Die Generierung dauert Zeit, daher folgt der Endpunkt dem Modell asynchroner Aufgaben. Deine erste Anfrage reicht eine Aufgabe ein; anschließend rufst du das Ergebnis ab, indem du den Aufgabenstatus abfragst, bis die Aufgabe einen Endzustand erreicht.

Halte diese drei Konzepte gedanklich getrennt, denn sie entsprechen drei verschiedenen Teilen des Clients:

  • Einreichen – die Nutzlast, die du sendest: das erste Frame-Bild, der Prompt und die Generierungsoptionen.
  • Aufgabenreferenz – die beim Einreichen zurückgegebene Kennung, mit der du die Aufgabe später abfragst.
  • Ergebnisabruf – wiederholtes Prüfen des Status, das schließlich das fertige Video (oder einen Fehler) zurückgibt.

Sobald du den Endpunkt als Aufgabenwarteschlange statt als RPC behandelst, wird der Rest der Integration – Polling-Intervall, Timeouts, Wiederholungen – zu einer gewöhnlichen asynchronen Pipeline statt zu einem Sonderfall. Wenn du neben dieser Übung auch die vollständigere Endpunktdokumentation konsultieren möchtest, öffne sie in einem anderen Tab und arbeite sie parallel durch.

Bevor du die Anfrage sendest

Drei Dinge musst du vor dem ersten Aufruf vorbereiten.

1. API-Zugangsdaten

Du brauchst einen HiAPI API-Schlüssel. Jede Anfrage sendet ihn als Bearer-Token über den Authorization-Header. Lege ihn nicht in der Versionsverwaltung ab – lies ihn aus einer Umgebungsvariable, statt ihn in ein Skript einzufügen.

export HIAPI_API_KEY="your-api-key-here"

2. Der Endpunktpfad

Alle Aufrufe laufen über die einheitliche HiAPI-Schnittstelle. Die Modellkennung, die du ansprichst, ist kling-4.0-flash/image-to-video. Deine Einreichungsanfrage und die späteren Statusabfragen zeigen auf denselben Modell-Namensraum, also lege diese Kennung als Konstante im Code ab, statt String-Literale überall zu verstreuen.

3. Ein vorbereitetes erstes Frame-Bild

Du brauchst ein Bild als Eröffnungsframe. Vor dem Senden musst du zwei Dinge klären:

  • Wie du es übergibst – als öffentlich erreichbare URL oder als kodierte Bilddaten, je nachdem, welche Form der Endpunkt in deinem Anwendungsfall akzeptiert.
  • Ob es wohlgeformt ist – korrektes Format, lesbar und nicht so groß, dass der Request-Body aufgebläht wird.

Eine praktische Regel: Halte den Request-Body klein und eindeutig. Wenn du eine URL übergibst, stelle sicher, dass sie ohne Authentifizierung erreichbar ist. Wenn du kodierte Daten übergibst, prüfe, dass die Kodierung genau der entspricht, die der Endpunkt erwartet.

Halte auch einen kurzen, konkreten Prompt bereit. Bild-zu-Video-Prompts funktionieren am besten, wenn sie Bewegung und Veränderung beschreiben (was sich bewegt, wie sich die Kamera bewegt), statt wiederzugeben, was im Frame bereits sichtbar ist.

Ein funktionierender curl-Aufruf

Hier ist ein vollständiger Einreichungsaufruf. Ersetze die Platzhalter durch deinen eigenen Schlüssel, dein Bild und deinen Prompt.

curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Slow dolly-in on the subject as light shifts across the scene",
    "image": "https://your-host.example/first-frame.jpg"
  }'

Punkt für Punkt:

  • -X POST – Einreichen ist eine schreibende Operation, keine Abfrage.
  • URL – die Modellkennung ist Teil des einheitlichen Endpunktpfads. Hier und nur hier gibst du das Modell an.
  • Authorization: Bearer $HIAPI_API_KEY – ein Header, den die Shell aus deiner Umgebungsvariable expandiert. Doppelte Anführungszeichen ermöglichen die Expansion und halten den Wert zugleich als ein einziges Argument zusammen.
  • Content-Type: application/json – der Body ist JSON; ohne diesen Header lehnen manche Gateways die Nutzlast ab oder parsen sie falsch.
  • -d '{ ... }' – der JSON-Body. prompt beschreibt die Bewegung; image liefert das erste Frame. Jedes Feld ist explizit – nichts hängt implizit von Position oder unsichtbaren Standardwerten ab.

Eine erfolgreiche Einreichung gibt einen JSON-Body mit einer Aufgabenkennung zurück. Erfasse sie – dieser Wert ist dein Handle auf die Aufgabe. Wenn du interaktiv erkundest, kannst du die Antwort durch einen JSON-Formatierer schicken, um die Kennung leichter zu kopieren:

curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool

Gehe nicht davon aus, dass das Video in dieser Antwort steckt. Das tut es nicht – die Antwort teilt dir nur mit, dass die Aufgabe angenommen wurde.

Dieselbe Anfrage in Python

Der Python-Client entspricht exakt der curl-Nutzlast. Ein Sprachwechsel ändert die Semantik nicht, nur den Mechanismus, mit dem die Bytes gesendet werden. Verwende requests und lies den Schlüssel aus der Umgebungsvariable:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"

def submit_job(prompt: str, image: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/{MODEL}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "image": image,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

job = submit_job(
    prompt="Slow dolly-in on the subject as light shifts across the scene",
    image="https://your-host.example/first-frame.jpg",
)
print(job)

Wichtige Punkte bei der Portierung:

  • json= statt -d – ein dict zu übergeben lässt requests den Body serialisieren und den Inhaltstyp setzen. Du erhältst dasselbe Wire-Format wie im curl-Beispiel, ohne JSON von Hand zu schreiben.
  • raise_for_status() – wandelt Nicht-2xx-Antworten in Ausnahmen um, damit du nicht versehentlich einen Fehler-Body als Aufgabenreferenz behandelst.
  • timeout=30 – das Einreichen sollte schnell sein. Ein großzügiger Timeout verhindert hängende Verbindungen, ohne echte langsame Aufrufe zu verschleiern.
  • Ein einziger Konstant für das Modell – wenn du später das Modell wechselst, änderst du nur eine Zeile.

Das zurückgegebene dict enthält die Aufgabenkennung, die der nächste Abschnitt nutzt.

Den asynchronen Aufgabenlebenszyklus handhaben

Das Integrationsmuster lautet erst einreichen, dann pollen. Zwei klar getrennte Phasen.

Phase 1: Einreichen und Referenz erfassen

Der submit_job-Aufruf aus dem vorigen Abschnitt gibt einen JSON-Body mit einer Aufgabenkennung zurück. Speichere sie. Jede spätere Statusprüfung braucht sie, und ihr Verlust bedeutet den Verlust der Aufgabe.

Phase 2: Pollen bis zum Endzustand

Eine Statusprüfung ist eine Leseanfrage zur selben Aufgabe. Wiederhole sie in festem Intervall, bis die Aufgabe einen Endzustand erreicht – abgeschlossen oder fehlgeschlagen. Eine einfache Schleife mit Obergrenze für die Versuche:

import time

def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/{MODEL}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()

        state = status.get("status")
        if state in ("succeeded", "failed"):
            return status
        time.sleep(interval)

    raise TimeoutError(f"Job {task_id} did not finish in time")

Bewusste Designentscheidungen, die sich lohnen:

  • Begrenze die Schleife. Polle niemals unbegrenzt. Maximale Versuche plus festes Intervall ergeben eine vorhersagbare maximale Wartezeit.
  • Schlafe zwischen den Prüfungen, nicht innerhalb der Anfrage. Zu häufiges Pollen verschwendet Kontingent und kann Rate-Limits auslösen.
  • Behandle Fehler als Endzustand. Eine fehlgeschlagene Aufgabe wird beim nächsten Poll nicht plötzlich erfolgreich – stoppe und lege den Fehler offen.
  • Unterscheide Warten von Fertig. Nur ein Endzustand beendet die Schleife; jeder andere Status bedeutet weiter warten.
  • Persistiere die Aufgaben-ID. Wenn der Prozess mitten im Polling abstürzt, willst du wiederaufnehmen können, statt neu zu generieren.

In der Produktion solltest du das Polling aus dem Request-Thread herausnehmen – an einen Hintergrund-Worker oder Queue-Consumer –, damit lang laufende Generierungen keinen Web-Request offen halten.

Die synchrone Audio-Option verwenden

Der Endpunkt bietet eine synchrone Audio-Option. In der Praxis bedeutet das für den Client eines: Wenn du sie aktivierst, blockiert der Aufruf, bis die Generierung abgeschlossen ist, statt eine Aufgabenreferenz zurückzugeben, die du pollen kannst.

Das ändert dein Design auf konkrete Weise:

  • Das Timeout-Budget muss größer werden. Ein blockierender Generierungsaufruf kann deutlich länger dauern als eine typische API-Anfrage. Setze das Client-Timeout so, dass es die gesamte erwartete Dauer abdeckt, nicht nur das Einreichen.
  • Keine Checkpoints unterwegs. Beim Polling kannst du nach einem Absturz mit der Aufgaben-ID wiederaufnehmen. Bei einem blockierenden Aufruf bedeutet ein Verbindungsabbruch, dass die Arbeit wiederholt werden muss.
  • Druck auf Threads und Connection-Pools. Ein blockierender Aufruf belegt einen Worker für die gesamte Dauer. In einem Webserver begrenzt das schnell deine Nebenläufigkeit.

Wann ist ein blockierender Aufruf akzeptabel? Wenn du ein Einmalskript, ein CLI-Tool oder eine Batch-Aufgabe ausführst, nichts anderes auf das Ergebnis wartet und Einfachheit vor Durchsatz geht. In diesen Fällen entfernt der synchrone Aufruf den Polling-Mechanismus vollständig und der Code wird kürzer.

Wann solltest du ihn vermeiden? In jedem benutzergerichteten Anfragepfad, in hochgradig nebenläufigen Diensten oder überall dort, wo ein Client timeouten und erneut versuchen könnte – ein wiederholter blockierender Aufruf kann deine Arbeit verdoppeln. In diesen Fällen behalte das asynchrone Einreichen-und-Pollen-Muster aus dem vorigen Abschnitt bei und deaktiviere die synchrone Option.

Häufige Fehler diagnostizieren

Behandle Fehler schichtweise. Der erste Fehler, den du siehst, ist meist der oberflächlichste, also behebe ihn und starte neu, statt mehrere Probleme auf einmal zu raten.

Authentifizierungsfehler

401 oder 403 bedeutet, dass die Zugangsdaten fehlen, falsch formatiert oder abgelehnt wurden. Prüfe, ob HIAPI_API_KEY tatsächlich in der Umgebung gesetzt ist, die dein Prozess sieht – eine in einer Shell exportierte Variable wird nicht an eine andere Shell oder einen Container weitergegeben. Stelle sicher, dass der Authorization-Header Bearer <key> lautet, mit genau einem Leerzeichen und ohne überflüssige Anführungszeichen aus dem Kopieren und Einfügen.

Fehlerhaft formatierte Nutzlast

400 bedeutet meist, dass der Body nicht geparst werden kann oder Pflichtfelder fehlen. Prüfe erneut, ob du Content-Type: application/json sendest, ob das JSON gültig ist (abschließende Kommas führen zum Fehler) und ob prompt und image beide vorhanden und nichtleere Strings sind. Gib zum Debuggen den Body aus, den du tatsächlich gesendet hast – nicht das dict, das du senden wolltest.

Probleme mit der Bild-Eingabe

Diese äußern sich meist als Validierungsfehler, nicht als offensichtliche Bildfehler. Prüfe der Reihe nach:

  • Erreichbarkeit – wenn du eine URL übergibst, rufe sie aus derselben Netzwerkumgebung ab, in der die Anfrage entsteht. Eine URL, die im Browser funktioniert, kann für die API durch eine Firewall blockiert oder durch Authentifizierung geschützt sein.
  • Format – stelle sicher, dass das Bild eine unterstützte, unbeschädigte Datei ist. Im Zweifel neu exportieren.
  • Größe – übermäßig große Bilder können die Validierung scheitern lassen oder den Body über Limits hinaus aufblähen.
  • Kodierung – wenn du kodierte Daten sendest, prüfe genau, dass die Kodierung der entspricht, die der Endpunkt erwartet; ein nicht passendes Präfix oder überflüssiger Leerraum führt zum Fehler.

Fehler auf Aufgabenebene

Wenn die Einreichung erfolgreich war, die Aufgabe aber mit Fehlerstatus endet, war die Anfrage wohlgeformt, aber die Generierung konnte nicht abgeschlossen werden. Lies den Prompt erneut, prüfe auf Mehrdeutigkeit oder physikalisch unsinnige Bewegung, und stelle sicher, dass das erste Frame-Bild tatsächlich als Ausgangspunkt taugt. Wiederhole den Versuch einmal mit einem vereinfachten Prompt, bevor du ein systemisches Problem annimmst – und protokolliere Aufgaben-ID und Fehlermeldung, um sie später korrelieren zu können.

Timeout der Polling-Schleife

Ein von wait_for_job geworfener TimeoutError bedeutet, dass deine Grenze zu eng ist, nicht dass die Aufgabe tot ist. Erhöhe die Versuche oder das Intervall und prüfe, ob du eine ältere, bereits beendete Task-ID pollst.

Beginne mit der minimalen Anfrage – ein Bild, ein kurzer Prompt, keine optionalen Felder – und erhöhe die Komplexität erst, wenn die Basis funktioniert. Wenn die Nutzlast klein und eindeutig ist, verschwinden die meisten Integrationsprobleme.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen