Steuerung von Anfangs- und Endbild in KI-Videos: Ein hiapi-Leitfaden für präzise Bewegung über verschiedene Modelle hinweg

Die meisten Bild-zu-Video-APIs empfangen lediglich ein statisches Bild und improvisieren dann die Bewegung. Nur wenige Modelle erlauben es, den Endpunkt der Kamerafahrt festzulegen und nicht nur den Startpunkt – man liefert ein Anfangs- und ein Endbild, und das Modell interpoliert dazwischen die Bewegung. Genau darin liegt der Unterschied zwischen „dieses Foto zum Leben erwecken“ und „diesen Übergang exakt umsetzen“.

Das Problem: Die Unterstützung der Endbild-Steuerung ist von Modell zu Modell uneinheitlich, selbst innerhalb derselben Produktlinie eines Anbieters kann sich die Flaggschiff-Stufe von der Fast-/Turbo-Stufe unterscheiden. Dieses Tutorial macht deutlich, welche hiapi-Videomodelle nur die Anfangsbild-Steuerung unterstützen und welche Anfangsbild + Endbild unterstützen, und nennt jeweils die tatsächlichen (und durchaus uneinheitlichen) Eingabefelder – so entdecken Sie nicht erst nach einigem Herumprobieren, dass das gewählte Modell Ihr Endbild stillschweigend ignoriert.

1. Was Sie benötigen

Einen hiapi-API-Key aus der Konsole (sk-...) sowie zwei Bild-URLs, auf die das Zielmodell zugreifen kann (öffentlich erreichbare HTTPS-URLs – der Task-Endpunkt unterstützt keine lokalen Datei-Uploads). Jedes der folgenden Modelle wird über dieselbe einheitliche Task-API angesprochen; sobald Ihr Key für eines der Modelle funktioniert, funktioniert er auch für alle anderen.

2. Minimales lauffähiges Beispiel

Die gesamte hiapi-Videogenerierung läuft über denselben Endpunkt: einen Task anlegen und dann abfragen (oder einen Callback nutzen – siehe Produktionsmuster), bis ein Endzustand erreicht ist.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video ist das typischste Beispiel für dieses Muster: input.image_urls akzeptiert eine oder zwei Bild-URLs. Übergibt man eine, wird nur das Anfangsbild verankert und der Rest frei gestaltet; übergibt man zwei, wird die zweite URL zum verbindlichen Endbild – das Modell weiß dann, wo die Kamerafahrt enden muss. Die Dauer ist eine ganze Zahl von 3–15 (Sekunden), resolution ist 720p / 1080p / 4k, und ein optionales boolesches sound fügt generierte Atmosphären-Audiospur hinzu. Ein aspect_ratio-Feld gibt es hier nicht – das Ausgabeformat folgt den bereitgestellten Bildern.

Nicht alle Modelle sind so aufgebaut. seedance-2.5/image-to-video erzielt denselben Effekt über zwei getrennt benannte Felder statt eines Arrays:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url ergibt nur in Kombination mit first_frame_url Sinn – man kann nur first_frame_url senden, um eine reine Anfangsbild-Aufnahme zu erhalten, aber nicht umgekehrt. Die Dauer dieses Modells reicht von 4–30 s, die Auflösung beträgt maximal 720p/1080p (keine 4K-Stufe), und aspect_ratio ist standardmäßig adaptive, d. h. es folgt dem Anfangsbild, statt einen expliziten Wert wie 16:9/9:16 anzunehmen.

Die Feldnamen unterscheiden sich tatsächlich von Modell zu Modell – image_urls gegenüber first_frame_url/last_frame_url – daher sollte jeder Modellwechsel als Schema-Änderung betrachtet werden und nicht als direktes Auswechseln.

Nicht jedes Modell unterstützt das

veo-3.1/image-to-video nimmt einen einzelnen image_url-String entgegen und hat überhaupt keinen Endbild-Parameter – man kann aspect_ratio (auto/16:9/9:16), resolution und eine feste duration-Enumeration (4, 6 oder 8 Sekunden) festlegen, aber das Endbild nicht fixieren. Eine Stufe tiefer in der Kling-Produktlinie gilt dasselbe: kling-3.0-turbo/image-to-video (die schnelle/günstige Variante von kling-3.0-omni) akzeptiert in image_urls höchstens einen Eintrag – kein Endbild und keine 4K-Auflösung. Wer Endbild-Steuerung benötigt, sollte die Flaggschiff-Stufe oder ein eigens dafür gebautes Modell (etwa seedance-2.5) wählen, statt sich auf den Namen der Modellfamilie zu verlassen.

3. Produktionsmuster

Im großen Maßstab Callbacks statt Polling verwenden. Im selben Request-Body ein callback-Objekt übergeben, statt in einer Schleife zu pollen:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" löst nur einmal aus, sobald der Task einen Endzustand erreicht – succeeded und failed sind beide Endzustände, daher sollte Ihr Webhook-Handler nach taskId deduplizieren, statt anzunehmen, dass ein Callback nur Erfolg bedeutet. Das Polling von GET /v1/tasks/:id eignet sich besser für lokales Debugging, seltene Einmal-Aufrufe oder als Abgleich-Fallback, wenn ein Callback nie ankommt (Netzwerkstörung, Ihr Endpunkt kurzzeitig offline).

Idempotenz. Wiederholungsversuche nach Zeitüberschreitung oder Verbindungsabbruch können bei unvorsichtiger Handhabung doppelte Tasks erzeugen – merken Sie sich die id, die der Erstellungsaufruf zurückgibt, und führen Sie vor dem Erwägen eines neuen Tasks zunächst ein GET auf diese ID als Wiederholungsversuch aus.

Ausgabe-URLs laufen ab. Das Feld expireAt an jedem Ausgabe-Eintrag ist nicht bloß Dekoration – unabhängig davon, ob Sie den Erfolg des Tasks per Callback oder Polling erfahren, sollten Sie das Video so bald wie möglich herunterladen und dauerhaft speichern (in Ihrem eigenen Speicher).

Authentifizierungsfehler. Ein falscher oder fehlender Key führt zu HTTP 401 mit {"error": {"code": "permission_denied", ...}}. Prüfen Sie diesen Status/Fehlercode explizit, statt anzunehmen, dass jeder Nicht-2xx-Status bedeutet, die Generierung selbst sei fehlgeschlagen – in der Fehlerbehandlung zwischen „mein Key ist falsch“ und „das Modell hat meine Eingabe abgelehnt“ zu unterscheiden, ist wertvoll, weil die Behebung völlig unterschiedlich ausfällt.

4. Verwandte Seiten

• Kling 3.0 Omni Bild-zu-Video-Modellseite – Preisgestaltung, Online-Ausprobieren und vollständige Parameterreferenz des im obigen Beispiel verwendeten Modells.
• Seedance 2.5 Bild-zu-Video-Modellseite – die Variante mit first_frame_url/last_frame_url.
• Authentifizierungsdokumentation – wie der Header Authorization: Bearer sk-... und die Key-Berechtigungsbereiche funktionieren.
• Dokumentation zum Erstellen von Tasks – die vollständige /v1/tasks-Request/Response-Referenz einschließlich der Callback-Optionen.
• hiapi-Preise – aktuelle Preise pro Sekunde und pro Auflösung (die Abrechnung variiert je nach Modell und Auflösung; bitte die Live-Seite prüfen statt fest eingetragener Zahlen).

5. Häufig gestellte Fragen

Welche hiapi-Videomodelle unterstützen die Endbild-Steuerung? kling-3.0-omni/image-to-video (über das image_urls-Array mit 2 Einträgen) und seedance-2.5/image-to-video (über first_frame_url + last_frame_url) unterstützen dies derzeit beide. veo-3.1/image-to-video und kling-3.0-turbo/image-to-video unterstützen es nicht – sie akzeptieren nur ein einzelnes Startbild.

Kann man nur das Endbild angeben und keinen Prompt? Beide Modelle akzeptieren (und erwarten in der Regel auch) einen prompt zusätzlich zu den Bildern – er steuert die Bewegung zwischen den beiden Bildern und nicht nur den Inhalt. Nicht jedes Modell lehnt einen leeren oder fehlenden Prompt direkt ab, aber eine explizite Beschreibung des Übergangs macht die Bewegung vorhersehbarer.

Müssen beide Bilder dasselbe Seitenverhältnis haben? Weder kling-3.0-omni/image-to-video noch seedance-2.5/image-to-video bietet ein explizites aspect_ratio, das unabhängig von den Bildern gesetzt wird – das Ausgabeformat folgt den Eingabebildern, daher führen unterschiedliche Seitenverhältnisse von Anfangs- und Endbild zu sichtbar unschönen Ergebnissen statt zu einem Fehler. Schneiden Sie beide Bilder vor dem Senden auf dasselbe Verhältnis zu oder ergänzen Sie Ränder entsprechend.

Was passiert, wenn man nur das Endbild ohne Anfangsbild sendet? Beide Modelle unterstützen das nicht – bei seedance-2.5 lässt sich last_frame_url nur zusammen mit first_frame_url verwenden; beim Array von kling-3.0-omni wird nach Position gelesen (erster Eintrag = Anfangsbild). Es gibt keinen „umgekehrten“ Modus, in dem nur das Endbild angegeben wird.

Ist die Endbild-Steuerung gleichbedeutend mit Video-zu-Video-Bewegungsübertragung? Nein – das ist eine andere Funktion (seedance-2.5/reference-to-video auf hiapi, das ein Referenz-Video entgegennimmt, um Bewegung oder Kamerafahrt zu steuern, statt zweier statischer Bilder). Anfangs-/Endbild-Steuerung interpoliert zwischen zwei Bildern; Referenz-Video-zu-Video imitiert das Bewegungsmuster eines vorhandenen Clips.

Ist die Generierung mit Endbild teurer als nur mit Anfangsbild? Beide Modelle rechnen pro Sekunde/pro Auflösung ab, nicht pro Eingabebild, daher erhöht das Hinzufügen eines Endbildes allein die Kosten nicht – die aktuellen Tarife finden Sie auf der Preisseite.