Tutorial
So rufen Sie hailuo-2.3/image-to-video über die HiAPI API auf: curl und Python
Auf dieser Seite
Was hailuo-2.3/image-to-video leistet und wann Sie es einsetzen
hailuo-2.3/image-to-video ist ein Image-to-Video-Modell, das über die einheitliche HiAPI-API bereitgestellt wird. Sie übergeben ein statisches Bild als erstes Frame sowie einen Prompt, der beschreibt, wie sich die Szene bewegen soll, und das Modell erzeugt einen kurzen Clip, der mit diesem Bild beginnt und die Animation darauf aufbauend vorantreibt.
Das Schlüsselwort ist erstes Frame. Bei Text-to-Video erfindet das Modell die gesamte Szene anhand des Prompts; bei Image-to-Video werden Komposition, Motiv, Beleuchtung und Stil an dem von Ihnen bereitgestellten Bild verankert. Es ist daher die passendere Wahl, wenn Sie bereits bestimmtes visuelles Material haben, das erhalten bleiben soll – Produktbilder, Charakterreferenzen, Storyboard-Frames, Konzept-Renderings – und darauf Bewegung legen möchten, statt es neu zu interpretieren.
Szenarien, für die dieser Endpunkt geeignet ist:
- Sie müssen die Konsistenz mit vorhandenem Material wahren. Ein Produktfoto sollte nicht als leicht abweichendes Produkt neu generiert werden, sondern sich bewegen.
- Sie erstellen Storyboards oder Animatics auf Basis statischer Frames und möchten Bewegung schnell vorab prüfen.
- Sie benötigen eine kontrollierbare Komposition: Kamera und Motivposition stammen aus dem Bild, der Prompt beschreibt nur die Bewegung.
Wenn kein Referenzbild vorhanden ist und das Modell die Kameraführung entwerfen soll, oder wenn visuelle Details besser per Text als durch ein Frame festgelegt werden, ist Text-to-Video die bessere Wahl.
Voraussetzungen und Abrufen des API-Schlüssels
Vor der ersten Anfrage benötigen Sie drei Dinge: ein HiAPI-Konto, einen API-Schlüssel und eine öffentlich erreichbare URL für das Bild des ersten Frames.
Konto und API-Schlüssel
Melden Sie sich bei HiAPI an und erstellen Sie einen API-Schlüssel in der Konsole. Behandeln Sie den Schlüssel vertraulich: Bewahren Sie ihn in einer Umgebungsvariable auf, statt ihn in Quelldateien einzufügen. Die Beispiele in dieser Anleitung lesen ihn aus HIAPI_API_KEY.
export HIAPI_API_KEY="your-api-key-here"
Erreichbare Bild-URL
Das als erstes Frame übergebene Bild muss serverseitig abrufbar sein – eine signierte Cloud-Storage-URL, ein CDN-Link oder eine beliebige öffentliche HTTPS-URL funktionieren; ein lokaler Dateipfad nicht. Wenn sich das Material an einem Ort mit Authentifizierung befindet, erzeugen Sie für die Anfrage eine zeitlich begrenzte signierte URL.
Bevor Sie einen Ablauf automatisieren, prüfen Sie in der aktuellen HiAPI-API-Referenz den derzeitigen Endpunktpfad, die Parameternamen und die zulässigen Werte. Modellschnittstellen entwickeln sich weiter, und das Hartkodieren von Parameternamen aus veralteten Tutorials ist eine häufige und vermeidbare Fehlerquelle. Aktuelle Preise und etwaige Kontingentregeln finden Sie im Preisbereich der Website – prüfen Sie dort, statt Annahmen zu treffen.
Anfragestruktur: Bildeingabe und Parameter
Konzeptionell besteht eine Image-to-Video-Anfrage aus drei Teilen: dem Modellidentifier, dem Bild und den Generierungsparametern.
Modellidentifier
Jeder Aufruf verweist auf hailuo-2.3/image-to-video. Legen Sie ihn an einer einzigen Stelle im Code ab, sodass ein späterer Modellwechsel nur eine Zeile erfordert.
Bild des ersten Frames
Dies ist die URL des statischen Bildes, mit dem das Video beginnt. Seitenverhältnis und Auflösung bestimmen die grundlegende Geometrie der Ausgabe – wählen Sie daher ein Bild, das bereits die gewünschte Komposition aufweist, statt nachträglich zuzuschneiden. Ein sauberes, gut ausgeleuchtetes Bild mit klarem Motiv führt zu deutlich vorhersehbarer Bewegung als eine unruhige Collage.
Prompt
Das Textfeld, das die Bewegung beschreibt – dazu im nächsten Abschnitt mehr.
Dauer und Auflösung
Image-to-Video-Aufgaben bieten üblicherweise Optionen für Clip-Länge und Ausgabeauflösung. Diese Parameter ändern sich am wahrscheinlichsten mit der Modellversion, daher nicht aus dem Gedächtnis hartkodieren. Öffnen Sie die aktuelle API-Referenz, lesen Sie die akzeptierten Feldnamen und zulässigen Werte und legen Sie diese Werte in einem Konfigurationsobjekt ab, statt Literale über den Code zu verstreuen. Wird ein Wert abgelehnt, nennt die API-Antwort in der Regel das betroffene Feld.
Der Request-Body ist JSON; die Antwort liefert einen Aufgabenidentifier statt eines fertigen Videos, was im Abschnitt zum Polling weiter unten behandelt wird.
Prompts schreiben, die glaubwürdige Bewegung erzeugen
Das Bild beschreibt bereits, was in der Szene zu sehen ist. Die Aufgabe des Prompts ist es, zu beschreiben, wie es sich bewegt. Ein Prompt, der das Motiv erneut beschreibt, verschwendet Modellkapazität; ein Prompt, der Bewegung, Kameraführung und Physik präzisiert, erzeugt deutlich bessere Clips.
Bewegung beschreiben, nicht Inhalt
Schwaches Beispiel: „Eine Frau im roten Mantel steht auf einer Brücke.“
Besseres Beispiel: „Die Frau dreht langsam den Kopf zur Kamera, der Mantel weht im Wind; die Kamera fährt sanft vorwärts.“
Motivbewegung und Kamerabewegung trennen
Seien Sie bei beidem explizit. „Langsame Vorwärtsfahrt“, „Handheld-Drift“, „statische Kamera“ und „Orbit nach rechts“ sagen dem Modell, wie sich das Bild selbst verändert; „Haare wehen“, „Dampf steigt auf“ und „Seiten blättern um“ beschreiben, was innerhalb des Bildes geschieht. Erst die Kombination beider ergibt eine kohärente Einstellung statt eines driftenden Bildes.
Physik respektieren
Verlangen Sie plausible Bewegung mit plausibler Geschwindigkeit: „Stoff wellt sich sanft“, „Wasser fließt stromabwärts“, „Rauch ringelt nach oben“. Vermeiden Sie Anweisungen, die der Szene widersprechen – ein sitzendes Motiv gehen zu lassen oder bei einer festen Produktaufnahme einen schnellen Schwenk zu verlangen, führt meist zu Artefakten.
Kurz und konkret bleiben
Zwei oder drei konkrete, physikalische Sätze schlagen einen ganzen Absatz voller Adjektive. Nennen Sie zuerst die Hauptbewegung, dann die Kameraführung und zuletzt Nebendetails wie Lichtveränderungen.
Aufgabe einreichen und Ergebnis abfragen
Die Videogenerierung dauert, daher ist die API asynchron. Der Lebenszyklus besteht aus drei Schritten:
1. Aufgabe erstellen
Senden Sie Bild-URL, Prompt und Parameter per POST an den Endpunkt. Eine erfolgreiche Antwort liefert einen Aufgabenidentifier und einen Ausgangsstatus, üblicherweise ähnlich queued oder processing. In dieser Antwort ist noch kein Video enthalten.
2. Aufgabe abfragen
Senden Sie regelmäßig GET-Anfragen für diesen Aufgabenidentifier. Jede Antwort meldet den Status und enthält bei Abschluss auch die Ergebnisnutzlast. Fragen Sie in vernünftigen Abständen ab – meist einige Sekunden – statt in einer engen Schleife, und begrenzen Sie die Anzahl der Versuche, damit eine hängende Aufgabe den Prozess nicht dauerhaft blockiert.
3. Video abrufen
Meldet der Status Erfolg, enthält die Antwort den Ort des Videos (üblicherweise eine URL), oft auch Metadaten wie die Dauer. Laden Sie es herunter oder speichern Sie es gemäß Ihren eigenen Aufbewahrungsregeln.
Gestaltungshinweise für die Produktion
- Aufgaben-ID persistieren. Wenn Ihr Worker mitten im Polling abstürzt, möchten Sie wiederaufnehmen können, statt neu einzureichen und für doppelte Aufgaben zu zahlen.
- Endgültige Fehler behandeln. Aufgaben können fehlschlagen; behandeln Sie einen Fehler als eigenen Zweig statt als „weiter pollen“.
- Einreichen und Abfragen entkoppeln. Reichen Sie in einem Web-Backend aus dem Request-Handler ein und fragen Sie aus einem Hintergrund-Worker ab, damit HTTP-Timeouts niemals eine laufende Generierung beenden.
Ausführbares curl-Beispiel
Das folgende Beispiel reicht eine Aufgabe ein. Ersetzen Sie Bild-URL und Prompt durch Ihre eigenen Inhalte; der Schlüssel stammt aus der zuvor gesetzten Umgebungsvariable.
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "Das Motiv im Bild dreht sich leicht zur Kamera und lächelt; die Kamera fährt langsam vorwärts, weiches Licht wandert über das Gesicht."
}'
Die Antwort enthält den Aufgabenidentifier. Fragen Sie ihn per GET ab:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Wiederholen Sie dies, bis der Status einen endgültigen Erfolg meldet, und lesen Sie dann die Video-URL aus der Nutzlast. Der hier gezeigte genaue Endpunktpfad und die Feldnamen dienen nur der Veranschaulichung des Musters – prüfen Sie sie gegen die aktuelle API-Referenz, bevor Sie etwas in Produktionscode übernehmen, denn Modellschnittstellen ändern sich tatsächlich.
Ausführbares Python-Beispiel
Dieses Skript reicht eine Aufgabe ein und fragt dann bis zum Abschluss ab, mit Timeout und grundlegender Fehlerbehandlung.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="Dampf steigt aus der Tasse auf; die Kamera driftet langsam nach rechts.",
)
result = poll_task(task)
print(result)
Da sich Status-Strings zwischen API-Versionen unterscheiden können, prüft der Code eine kleine Menge gängiger Erfolgs- und Fehlerwerte statt eines einzelnen Literals – verifizieren Sie die genaue Terminologie in der API-Referenz und passen Sie die Menge entsprechend an. Wenn Sie mehrere Medien-Pipelines bauen, lässt sich diese Hilfsfunktion gut separat wiederverwenden.
Häufige Fehlermuster und Debugging
Die meisten Probleme mit diesem Endpunkt fallen in die folgenden Kategorien.
Bild abgelehnt oder nicht abrufbar
Der Dienst muss Ihr Bild herunterladen können. Bei Abruf- oder Validierungsfehlern prüfen Sie, ob die URL öffentliches HTTPS ist, ob sie abgelaufen ist (signierte URLs laufen ab) und ob Format und Größe innerhalb der dokumentierten Grenzen liegen. Ein schneller Test: Öffnen Sie die URL in einem Inkognito-Fenster – verlangt sie eine Anmeldung, kann auch der Server sie nicht lesen.
Ungültige Parameter
Abgelehnte Dauer, Auflösung oder unbekannte Felder führen in der Regel zu einem Validierungsfehler, der das Feld benennt. Vergleichen Sie Ihre Nutzlast mit der aktuellen API-Referenz statt mit einem Tutorial, und protokollieren Sie den vollständigen Fehler-Body – die Fehlermeldung ist konkreter als der bloße HTTP-Statuscode.
Authentifizierungsfehler
401 oder 403 bedeuten fast immer, dass der Schlüssel fehlt, falsch formatiert ist oder die Zugriffsberechtigung fehlt. Vergewissern Sie sich, dass der Authorization-Header vorhanden ist und die Umgebungsvariable tatsächlich in der Shell oder dem Prozess exportiert wurde, der die Anfrage ausführt.
Polling-Timeout
Bleibt die Aufgabe nach Ihrem Timeout noch bei processing, prüfen Sie zunächst, ob Sie die richtige Aufgaben-ID abfragen, und verlängern Sie dann den Timeout. In der Produktion sollten Sie zwischen „läuft noch“ und „hängt“ unterscheiden: Persistieren Sie den Status und lassen Sie einen Worker das Polling wiederaufnehmen, statt neu einzureichen, denn erneutes Einreichen verschwendet Aufgaben.
Aufgabe schlägt nach dem Einreichen fehl
Fehlgeschlagene Aufgaben deuten meist auf eine Kombination aus Prompt und Bild hin – widersprüchliche Bewegungsanweisungen oder ein erstes Frame, das der angeforderten Bewegung widerspricht. Vereinfachen Sie den Prompt, versuchen Sie ein saubereres erstes Frame und starten Sie erneut.
Ausgabe wirkt falsch
Ist die Bewegung schwach oder seltsam, liegt die Lösung fast immer im Prompt: Benennen Sie die Hauptbewegung klar, trennen Sie Kameraführung von Motivbewegung und halten Sie die physikalische Bewegung plausibel. Protokollieren Sie Request-ID und Aufgaben-ID, um einen schlechten Clip den genauen Eingaben zuordnen zu können, die ihn erzeugt haben. Vor der Veröffentlichung sollten Sie Parameternamen und aktuelle Preise in der API-Referenz und im Preisbereich bestätigen.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen