So rufen Sie kling-4.0/image-to-video auf HiAPI auf: curl, Python und Polling

Was der Endpunkt kling-4.0/image-to-video leistet

kling-4.0/image-to-video verwandelt ein einzelnes statisches Bild in einen kurzen generierten Videoclip. Auf HiAPI wird er als aufgabenbasierter Endpunkt bereitgestellt: Sie übermitteln ein Bild und eine beschreibende Aufforderung, wie sich die Szene bewegen soll, und die API gibt sofort ein Aufgaben-Handle zurück, nicht das fertige Video.

Auf Anfrageebene muss der Aufrufer Folgendes bereitstellen:

• den Modellbezeichner (kling-4.0/image-to-video),
• das Quellbild (normalerweise eine öffentlich erreichbare Bild-URL),
• eine Textbeschreibung, die steuert, wie sich das Bild bewegt oder was in der Szene geschehen soll,
• alle zusätzlichen Generierungsoptionen, die dieser Endpunkt für dieses Modell vorsieht.

Zurückgegeben wird nicht das Video selbst. Die Übermittlungsantwort trägt einen Aufgabenbezeichner und einen Anfangszustand. Der eigentliche Videoclip steht erst zur Verfügung, nachdem die Generierungsaufgabe abgeschlossen ist; dann können Sie ihn abrufen, indem Sie auf diesen Bezeichner verweisen.

Diese Aufteilung ist das vollständige mentale Modell dieses Endpunkts: übermitteln → Aufgaben-ID erhalten → Status abfragen → Ergebnis herunterladen. Jeder Abschnitt weiter unten ist eine Variante dieses Zyklus.

Da der Endpunkt asynchron ist, hat Ihr Integrationscode zwei Aufgaben statt einer: Er muss eine wohlgeformte Übermittlungsanfrage senden und den nachfolgenden Ablauf verwalten, bis die Aufgabe einen Endzustand erreicht. Wenn Sie beides richtig machen, bleibt nur noch Routinearbeit übrig.

Voraussetzungen und Authentifizierung

Vor jedem Aufruf benötigen Sie zwei Dinge: ein HiAPI-Konto mit Zugriff auf dieses Modell und einen in der Konsole ausgestellten API-Schlüssel.

Die Authentifizierung erfolgt pro Anfrage. Jeder API-Aufruf enthält Ihren Schlüssel im HTTP-Header – das Standardmuster ist ein Bearer-Autorisierungsheader:

Authorization: Bearer <YOUR_HIAPI_API_KEY>

Lassen Sie den Schlüssel niemals in die Versionsverwaltung gelangen. Üblich ist:

• Ihn in einer Umgebungsvariable zu speichern (z. B. HIAPI_API_KEY) und zur Laufzeit zu lesen.
• Ihn niemals in Client-Code einzufügen oder in curl-Befehle, die Sie später in ein Repository committen.
• Ihn in der Konsole zu rotieren, sobald er kompromittiert wurde.

Exportieren Sie ihn in der Shell, damit sowohl die curl- als auch die Python-Beispiele unten ihn lesen können:

export HIAPI_API_KEY="your-key-here"

Sie benötigen außerdem eine erreichbare Bild-URL. Der Endpunkt verwendet Bilder per Referenz, daher funktioniert ein lokaler Dateipfad auf Ihrem Laptop nicht – hosten Sie das Bild unter einer stabilen HTTPS-URL oder, falls die Plattform einen Ressourcenmechanismus bietet, laden Sie das Bild hoch und verwenden Sie die zurückgegebene Referenz.

Sobald der Schlüssel exportiert und das Bild erreichbar ist, können Sie die Aufgabe übermitteln.

Eine curl-Anfrage Schritt für Schritt erklärt

Eine vollständige Übermittlungsanfrage sieht so aus:

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": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "A slow camera push-in as the subject turns toward the light; soft afternoon shadows"
    }
  }'

Teilweise erklärt:

• -X POST — die Aufgabenerstellung erfolgt per POST, nicht per GET. Die Anfrage trägt einen Body, der den Job beschreibt.
• URL — der einheitliche HiAPI-Aufgabenendpunkt. Für aufgabenbasierte Modelle ist dies dieselbe Route; das Modell wird im Body ausgewählt, nicht im Pfad.
• Authorization — Ihr Schlüssel, wie im vorigen Abschnitt beschrieben.
• Content-Type: application/json — der Body ist JSON; fehlt dieser Header oder ist er falsch geschrieben, lehnt der Server die Anfrage in der Regel ab, bevor sie das Modell erreicht.
• model — der wörtliche String kling-4.0/image-to-video. Betrachten Sie ihn als exakt und groß-/kleinschreibungssensitiv; ein Tippfehler erzeugt einen Modell-nicht-gefunden-Fehler statt eines hilfreichen Hinweises.
• input.image — das statische Quellbild als URL. Dies ist das Frame, das das Modell animieren soll; wählen Sie daher ein klares, gut komponiertes Bild.
• input.prompt — die Anweisung in natürlicher Sprache. Beschreiben Sie Bewegung und Kameravorhalten (Heranzoomen, Schwenken, Bewegung des Motivs) sowie die Gesamtstimmung. Vage Prompts erzeugen vage Bewegung.

Die unmittelbare Antwort ist ein Aufgabenobjekt, nicht das Video. Es enthält den Bezeichner des Jobs und ein Statusfeld – nach der Übermittlung normalerweise so etwas wie „in Warteschlange“ oder „ausstehend“. Speichern Sie diesen Bezeichner; er ist die einzige Information, die Sie später zum Prüfen des Jobs benötigen.

Zu diesem Zeitpunkt existiert der Videoclip noch nicht. Das ist erwartetes Verhalten; der nächste Abschnitt zeigt, wie man damit umgeht.

Derselbe Aufruf in Python

Die Python-Version macht genau dasselbe – derselbe Endpunkt, dieselben Header, derselbe Body –, daher ändert Ihre Werkzeugwahl nichts am Protokoll.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "A slow camera push-in as the subject turns toward the light; "
                  "soft afternoon shadows",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Einige Punkte, die in der Praxis zu beachten sind:

• Verwenden Sie json=payload statt manuell serialisierter Strings. Das setzt den Inhaltstyp für Sie und vermeidet Anführungszeichenfehler.
• Legen Sie die Übermittlungsanfrage und die nachfolgenden Operationen in dieselbe Funktion oder Klasse, damit die Aufgaben-ID nicht zwischen den Schritten verloren geht.
• Setzen Sie explizite Timeouts. Der Übermittlungsaufruf sollte schnell zurückkehren; er erstellt nur den Job, er wartet nicht auf das Video.
• Rufen Sie nicht raise_for_status() auf und nehmen dann trotzdem an, die Aufgabe existiere – eine Nicht-2xx-Antwort bedeutet, dass keine Aufgabe erstellt wurde; der Fehler-Body sagt Ihnen meist, welches Feld falsch war.

Wenn Sie einen Dienst bauen, kapseln Sie diesen Aufruf in einem kleinen Client – eine Methode zum Übermitteln, eine zum Prüfen des Status. So bündeln Sie Wiederholungen, Logging und Schlüsselverwaltung an einer Stelle statt an jedem Aufrufpunkt.

Eine asynchrone Aufgabe bis zur Fertigstellung abfragen

Die Bild-zu-Video-Generierung dauert deutlich länger als eine Chat-Completion – das Modell muss viele Frames synthetisieren, kodieren und das Ergebnis speichern. Der Videoclip kann nicht zurückgegeben werden, ohne die Verbindung über einen längeren Zeitraum offen zu halten, daher ist dieser Endpunkt von Natur aus asynchron.

So prüfen Sie den Status

Fragen Sie die Aufgabe per GET-Anfrage anhand ihres Bezeichners ab:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Die Antwort beschreibt den Job: seinen Status und, sobald fertig, die Ausgabe. Der Status durchläuft in der Regel vom Zustand „in Warteschlange“ über „in Ausführung“ bis zu einem Endzustand – etwa Erfolg oder Fehlschlag mit einer Fehlermeldung.

Einfache Polling-Schleife in Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # gentle backoff, capped

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

Hinweise zum Backoff

• Beginnen Sie mit kurzen Abständen und erhöhen Sie diese schrittweise. Die Generierung ist nicht in der ersten Sekunde fertig, daher verschwendet häufiges Anfragen des Endpunkts nur Kontingent und löst Ratelimits aus.
• Begrenzen Sie den Abstand, damit abgeschlossene Jobs zeitnah bemerkt werden – im eingeschwungenen Zustand genügen einige Sekunden.
• Setzen Sie immer eine harte Frist. Ohne Grenze ist eine nie fertig werdende Aufgabe nicht von einer ungewöhnlich lange dauernden zu unterscheiden.
• Fragen Sie aus einem Hintergrund-Worker oder einem geplanten Job ab, statt eine Web-Anfrage zu blockieren. Wenn ein Benutzer in der UI wartet, soll das Frontend Ihren eigenen Status-Endpunkt abfragen.
• Wiederholen Sie bei vorübergehenden Netzwerkfehlern in Statusaufrufen, aber nicht bei Aufgaben, die bereits failed gemeldet haben – dann ist das korrekte Vorgehen, eine neue Aufgabe zu übermitteln.

Den zurückgegebenen Videoclip abrufen und speichern

Wenn das Polling einen erfolgreichen Endzustand zurückgibt, enthält das Aufgabenobjekt eine Ausgabereferenz für das generierte Video – eine Ressourcen-URL oder eine gleichwertige Referenz auf das fertige Video.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Hier sind meist zwei Designentscheidungen zu treffen.

Rechtzeitig herunterladen. Ausgabe-URLs sind oft zeitlich begrenzt. Wenn Sie den Videoclip behalten wollen, kopieren Sie ihn in Ihren eigenen Speicher, statt die rohe URL an Benutzer zu geben und zu hoffen, dass sie gültig bleibt.

Metadaten zusammen mit der Datei speichern. Persistieren Sie Aufgaben-ID, Prompt, Quellbildreferenz und Erstellungszeit zusammen mit dem Video. Wenn später jemand fragt, warum der Videoclip so aussieht, ist dieser Datensatz die Antwort.

Für einen Dienst ist ein übliches Muster: im Backend generieren, die Datei im Objektspeicher ablegen und dem Client Ihre eigene stabile URL zurückgeben. So kontrolliert Ihre Anwendung Zugriff, Ablauf und Caching, statt sich auf die Lebensdauer der generierten Ressource zu verlassen.

Wenn Sie mit einer anderen Bewegung neu generieren möchten, übermitteln Sie eine neue Aufgabe mit angepasstem Prompt – jede Aufgabe ist unabhängig, eine bereits abgeschlossene Aufgabe muss nicht geändert werden.

Fehlgeschlagene Anfragen beheben

Wenn etwas schiefgeht, gehen Sie von der Anfragestruktur nach außen vor. Die meisten Fehler lassen sich auf wenige Ursachen zurückführen.

Der Übermittlungsaufruf gibt einen Fehler zurück

• Falscher Modell-String. kling-4.0/image-to-video muss exakt passen, einschließlich Groß-/Kleinschreibung und Schrägstrich. Drucken Sie den tatsächlich gesendeten String aus, statt der Quelldatei zu vertrauen.
• Authentifizierung abgelehnt. Stellen Sie sicher, dass der Header Authorization: Bearer <key> lautet – kein nackter Schlüssel, kein Query-Parameter – und dass die Umgebungsvariable in derselben Shell bzw. demselben Prozess gesetzt ist, der die Anfrage ausführt.
• Bild nicht erreichbar. Das Bild muss von der Plattform über HTTPS abrufbar sein. localhost-URLs, private Buckets oder Hosts mit Hotlink-Schutz schlagen fehl. Öffnen Sie die URL in einem Inkognito-Browser und prüfen Sie, ob sie ohne Authentifizierung aufgelöst wird.
• Feld fehlt oder falsch benannt. Der Body verschachtelt die Modelleingaben unter input. prompt oder image auf die oberste Ebene statt in input zu setzen, ist ein häufiger Fehler; Validierungsfehler nennen in der Regel den Feldnamen.
• Inhaltstyp. Ein JSON-Body ohne Content-Type: application/json wird abgelehnt, bevor das Modell überhaupt ins Spiel kommt.

Aufgabe wurde erstellt, war aber nie erfolgreich

• Zu selten oder gar nicht abgefragt. Prüfen Sie, ob Ihre Schleife tatsächlich läuft und ob sie die Statuswerte vergleicht, die die API tatsächlich zurückgibt. Ein Tippfehler in der Endzustandsprüfung führt zu einer Endlosschleife.
• Aufgabe wird failed. Lesen Sie die Fehlermeldung im Aufgabenobjekt; sie weist meist auf die Eingabe hin – etwa ein nicht dekodierbares Bild.
• Sie haben die Frist erreicht. Wenn der Job nahe dem Timeout noch läuft, erhöhen Sie das Limit, statt wiederholt neu zu übermitteln; Letzteres erhöht nur Last und Kosten.
• Ausgabelink abgelaufen. Wenn die Aufgabe erfolgreich war, der Download aber 404 zurückgibt, ist zwischen Abschluss und Abruf zu viel Zeit vergangen. Laden Sie direkt nach dem Erfolg herunter.

Eine schnelle Diagnose-Gewohnheit: Protokollieren Sie bei den ersten Integrationen den Body der Übermittlungsantwort wörtlich. Er sagt Ihnen die Aufgaben-ID, den Anfangszustand und die genauen Feldnamen, die dieser Endpunkt zurückgibt, und beseitigt damit das Rätselraten bei jedem späteren Fehler.