Tutorial
muse-video-1.0 Image-zu-Video-API-Tutorial: curl und Python Requests
Auf dieser Seite
Was der muse-video-1.0 Image-zu-Video-Endpunkt erfordert
Der Endpunkt muse-video-1.0/image-to-video wandelt ein einzelnes Standbild in einen kurzen Videoclip um. Bevor Sie die erste Codezeile schreiben, hilft es Ihnen, die Struktur der Anfrage zu verstehen, damit Sie die korrekte Nutzlast auf Anhieb zusammenstellen können.
Auf hoher Ebene umfasst ein Aufruf vier Aspekte:
- Modell-Routing – Sie geben das Modell über die einheitliche HiAPI-API als
muse-video-1.0/image-to-videoan. - Eingabebild – Das Standbild, das als Ausgangspunkt für die Animation dient. Dies ist die erforderliche kreative Eingabe.
- Generierungsoptionen – Audioverhalten und Dauerstufe, die die Eigenschaften der Ausgabe und nicht das Quellmaterial prägen.
- Asynchrone Ausführung – Die Generierung liefert das fertige Video nicht inline zurück. Sie reichen zuerst eine Aufgabe ein und fragen dann per Polling das Ergebnis ab.
Der letzte Punkt wird von Entwicklern am häufigsten übersehen. Da das Rendern Zeit benötigt, basiert der Endpunkt auf einem Aufgabenmechanismus: Der erste Aufruf bestätigt Ihre Anfrage und gibt ein Handle zurück; anschließend verfolgen Sie den Status, bis das Video bereit ist. Entwerfen Sie Ihren Client von Anfang an um diesen zweistufigen Ablauf herum, statt das Polling nachträglich zu ergänzen.
Der Anfragetext selbst ist JSON. Die Felder sind gruppiert: Das Bild befindet sich in einem eigenen input-Block, während Audio und Dauer daneben als Generierungseinstellungen stehen. Behalten Sie dieses mentale Modell bei – Trennung von Eingabe, Optionen und Aufgabenlebenszyklus –, dann bleibt der Rest dieses Tutorials unkompliziert.
Authentifizierung
Jede Anfrage wird mit Ihrem HiAPI-API-Schlüssel authentifiziert, der als Bearer-Anmeldeinformation im Header Authorization übergeben wird. Behandeln Sie den Schlüssel als geheim: Laden Sie ihn aus einer Umgebungsvariable, statt ihn in einem Skript fest zu codieren, das Sie möglicherweise weitergeben.
export HIAPI_API_KEY="your_api_key_here"
Sobald der Schlüssel exportiert ist, haben Sie alles, was zum Verständnis der Anfrage nötig ist. Die folgenden Abschnitte bauen die Anfragetext Schritt für Schritt auf.
Vorbereiten und Hochladen Ihres ersten Frames
Das erste Frame ist der kreative Anker der gesamten Aufgabe. Was Sie bereitstellen, wird zum nullten Frame, von dem aus das Modell vorwärts animiert. Wenn Sie es richtig machen, vermeiden Sie verschwendete Generierungsversuche.
Praktische Empfehlungen für das Quellframe
- Verwenden Sie klare Standbilder hoher Qualität. Was als Einzelbild gut lesbar ist, bietet dem Modell den besten Ausgangspunkt.
- Wählen Sie ein Seitenverhältnis, das zur Zielausgabe passt. Breite Querformate und hochformatige Bilder führen zu sehr unterschiedlichen Kompositionen; legen Sie die Ausrichtung daher bereits vor dem eigentlichen Upload fest.
- Vermeiden Sie starke Bewegungsunschärfe oder unklare Motive. Visuell stabile Standbilder erzeugen vorhersehbarere Animationen.
- Stellen Sie sicher, dass die Datei zum Zeitpunkt der Anfrage erreichbar ist. Ob Sie eine URL oder eine codierte Nutzlast übergeben – sorgen Sie dafür, dass die Referenz in dem Moment erreichbar ist, in dem die Aufgabe eingereicht wird.
Wie das Bild in die Anfrage gelangt
Das Bild wird im input-Block des JSON-Anfragetexts bereitgestellt. Eine minimale Bildeingabe sieht so aus:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
Wenn Ihr Quellbild lokal liegt, hosten Sie es an einem für die Anfrage erreichbaren Ort oder übergeben Sie es in der vom Endpunkt akzeptierten codierten Form. Die entscheidende Regel: Der Wert in input.image muss zum Zeitpunkt der Aufgabenerstellung zu echten Bildinhalten aufgelöst werden – beschädigte oder abgelaufene Links schlagen bereits beim Einreichen fehl, nicht erst beim Polling, was tatsächlich ein nützliches frühes Signal ist.
Vor der Generierung validieren
Ein schneller Plausibilitätstest lohnt sich: Öffnen Sie die Bild-URL im Browser, bestätigen Sie, dass sie lädt, und prüfen Sie dann, ob die Abmessungen zu Ihrer erwarteten Ausgabe passen. Zwei Sekunden Prüfung hier ersparen später verwirrende Debugging-Sitzungen.
Sobald das erste Frame vorbereitet und erreichbar ist, können Sie mit den Generierungsoptionen fortfahren.
Audio-Parameter und Dauerstufen festlegen
Neben dem Bild bietet muse-video-1.0/image-to-video zwei Arten von Optionen, die die Eigenschaften der Ausgabe verändern: Audioverhalten und Dauer.
Audio-Parameter
Audio wird durch ein Feld im Anfragetext dargestellt, das neben Ihrem input steht. Legen Sie die Absicht vor dem Aufruf fest:
- Stumme Ausgabe – Lassen Sie Audio deaktiviert, wenn Sie Ihre eigene Tonspur später hinzufügen möchten oder eine saubere Videospur benötigen.
- Audio aktivieren – Aktivieren Sie Audio, wenn der Clip eigenen Ton enthalten soll. Prüfen Sie diese Option im Anfragetext explizit, statt Standardwerte anzunehmen.
Da die Audioverarbeitung eine Eigenschaft der Anfrage selbst ist und kein Nachbearbeitungsschritt, lohnt es sich, sie festzulegen, bevor Sie skalieren. Wenn Ihre Pipeline stumme und vertonte Clips mischt, modellieren Sie diese Wahl als expliziten Parameter in Ihrem Client-Code, damit nichts versehentlich passiert.
Dauerstufen
Der Endpunkt erlaubt es Ihnen, eine Dauerstufe für den Clip zu wählen. Betrachten Sie die Dauer als bewusste kreative und kostenbezogene Entscheidung:
- Kürzere Stufen eignen sich für schnelle Vorschauen, Social-Media-Clips und Storyboard-Tests, bei denen Sie auf vielen Quellbildern schnell Feedback wünschen.
- Längere Stufen geben der Animation mehr Raum zur Entfaltung und passen besser zu Key-Visual-Aufnahmen oder Sequenzen, die Atmung brauchen.
Die Dauer wird nach Ausgabesekunden abgerechnet, daher wirkt sich die gewählte Stufe direkt auf den Verbrauch aus. Es bringt keinen Vorteil, lange Clips nur für eine schnelle visuelle Prüfung zu rendern – iterieren Sie mit kurzen Stufen, während Sie das erste Frame verfeinern, und heben Sie die siegreichen Einstellungen dann auf längere Stufen.
Diese Optionen zusammenstellen
In JSON stehen Audio- und Dauer-Einstellungen neben dem input-Block:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
Verwenden Sie die exakten Stufenbezeichner aus der Endpunktdokumentation und raten Sie nicht. Der nächste Abschnitt macht daraus eine ausführbare Anfrage.
Eine funktionierende curl-Anfrage
Sobald der Anfragetext zusammengestellt ist, folgt hier der curl-Befehl für die initiale Einreichung. Er erstellt die Aufgabe; er liefert nicht das fertige Video zurück.
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
Einige Anmerkungen zu diesem Befehl:
- Die URL benennt das Modell. Sie benötigen keinen separaten Client pro Modell; der Pfad identifiziert bereits
muse-video-1.0/image-to-video. - Der Header trägt Ihren Schlüssel.
$HIAPI_API_KEYwird aus der zuvor exportierten Umgebungsvariable expandiert, sodass der Schlüssel nie im Skript selbst erscheint. - Der Anfragetext ist genau die Nutzlast, die Sie gerade aufgebaut haben. Bild-URL, Audio-Flag und Dauerstufe werden gemeinsam übergeben.
Die Antwort ist eine Aufgabenbestätigung: Sie enthält den Bezeichner der soeben erstellten Aufgabe. Kopieren Sie diesen Bezeichner – er wird im Polling-Schritt benötigt. Wenn Sie nur experimentieren, können Sie die Antwort mit einem JSON-Formatierer aufbereiten, um die Job-ID leichter zu finden.
Wenn die Einreichung fehlschlägt, sind die Fehler meist sofort und konkret: fehlerhafter JSON-Anfragetext, fehlende Bildreferenz oder nicht erkannte Optionswerte. Diese schnelle Rückkopplungsschleife ist genau der Grund, warum es sich lohnt, die Einreichung getrennt zu testen, bevor Sie das Polling anbinden.
Dieselbe Anfrage in Python
Die meisten Integrationen landen letztlich bei Python, daher folgt hier die äquivalente Einreichung mit der Standardbibliothek – ohne Drittanbieter-SDK.
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
Das Skript entspricht dem curl-Aufruf Feld für Feld. Einige Gewohnheiten, die es sich anzueignen lohnt:
- Bewahren Sie die Nutzlast in einem Dictionary auf. Wenn Sie sie als Python-Dictionary aufbauen, können Sie dieselbe Struktur an jede HTTP-Bibliothek übergeben –
urllib,requestsoder einen asynchronen Client –, ohne die Logik neu zu schreiben. - Lesen Sie den Schlüssel aus der Umgebung.
os.environhält Anmeldeinformationen aus der Versionskontrolle heraus. - Parsen Sie die Antwort sofort als JSON. Das Extrahieren der Job-ID in eine benannte Variable macht den Polling-Schritt lesbarer.
Wenn Sie die Bibliothek requests bevorzugen, ändert sich nur die Transportebene: Sie bauen dasselbe payload-Dictionary auf, senden es mit Ihrem Header-Set und rufen dann .json() auf der Antwort auf. Endpunkt, Header und Anfragetext bleiben identisch.
Nachdem die Aufgabe eingereicht und ihr Bezeichner erfasst ist, besteht die verbleibende Arbeit darin, auf das Ergebnis in der richtigen Weise zu warten.
Asynchrone Aufgaben per Polling abfragen und das Video abrufen
Die Videogenerierung erfolgt nicht sofort, daher ist der Endpunkt asynchron. Nach der Einreichung fragen Sie den Aufgabenstatus ab, um zu erfahren, wann das Rendering abgeschlossen ist, und rufen dann die Ausgabe ab.
Die Polling-Schleife
Eine robuste Schleife tut drei Dinge: Sie wartet zwischen den Prüfungen, setzt ein Limit, damit sie nicht endlos läuft, und unterscheidet zwischen „wird noch verarbeitet“, „abgeschlossen“ und „fehlgeschlagen“.
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
Designhinweise für die Produktion
- Verwenden Sie ein angemessenes Intervall. Fünf Sekunden sind ein vernünftiger Ausgangspunkt; hämmern Sie nicht auf den Status-Endpunkt ein.
- Begrenzen Sie stets die Anzahl der Versuche. Die Obergrenze
max_attemptsverwandelt endloses Warten in einen klaren Fehler, der protokolliert und alarmiert werden kann. - Behandeln Sie Fehlerzustände explizit. Fehlgeschlagene Aufgaben enthalten Diagnoseinformationen – machen Sie sie sichtbar, statt stillschweigend dieselbe Eingabe erneut zu versuchen.
- Persistieren Sie die Job-ID. Wenn Ihr Prozess neu startet, können Sie das Polling fortsetzen, statt für eine neue Generierung zu bezahlen.
Die Ausgabe abrufen
Bei erfolgreicher Aufgabe enthält die Statusantwort eine Ausgabereferenz für das fertige Video. Laden Sie es zeitnah in Ihren eigenen Speicher herunter, statt sich auf langfristig gültige Links zu verlassen. Sobald Sie die Datei lokal oder in Ihrem Bucket haben, ist die Generierung aus Sicht der Pipeline abgeschlossen.
Das ist der gesamte Lebenszyklus: einreichen, abfragen, abrufen. Wenn Sie die beiden Phasen im Code trennen, bleibt jede einzelne einfach.
Häufige Fallstricke und Debugging-Tipps
Die meisten Integrationsprobleme bei der Verwendung von muse-video-1.0/image-to-video lassen sich auf wenige Kategorien zurückführen. Folgendes sollten Sie prüfen, wenn etwas nicht funktioniert.
Probleme mit der Bildeingabe
- Bildreferenz nicht erreichbar. Wenn die URL Authentifizierung erfordert oder abgelaufen ist, schlägt die Aufgabe beim Einreichen fehl. Hosten Sie das Frame während der Anfrage an einem öffentlich lesbaren Ort.
- Nicht passendes Seitenverhältnis. Ein hochformatiges Standbild für eine Querformat-Ausgabe zu erzwingen, führt zu unschönen Zuschnitten oder schwarzen Balken. Stellen Sie die Quellausrichtung passend zum Ziel ein.
- Falscher Inhalt. Es ist leicht, versehentlich auf ein Thumbnail oder Platzhalterbild statt auf das echte Frame zu verweisen. Prüfen Sie, ob die URL das erwartete Bild öffnet.
Parameterfehler
- Dauerwerte raten. Verwenden Sie die in der Endpunktdokumentation exakt angegebenen Stufenbezeichner. Nicht erkannte Werte sind eine häufige Ablehnungsursache.
- Audio-Flag vergessen. Wenn Sie die Audio-Einstellung weglassen und dennoch Ton erwarten, erhalten Sie möglicherweise einen stummen Clip. Geben Sie explizit an, ob Audio benötigt wird.
- Top-Level-Felder mit input-Feldern verwechseln. Das Bild gehört in
input; Audio und Dauer sind Geschwister voninput, keine Kinder. Falsche Verschachtelung erzeugt verwirrende Validierungsmeldungen.
Polling-Fehler
- Einreichen als Abschluss betrachten. Die erste Antwort ist nur eine Bestätigung, nicht das Video. Führen Sie stets Statusprüfungen nach.
- Unbegrenztes Polling. Eine Schleife ohne Obergrenze hängt Ihren Worker auf, wenn die Aufgabe stockt. Fügen Sie Obergrenzen und Timeout-Fehler hinzu.
- Fehler ignorieren. Aufgaben, die im Fehlerzustand enden, erzeugen niemals ein Video; fangen Sie dies ab und prüfen Sie die Diagnoseinformationen, statt weiter zu warten.
- Lange Wartezeiten bei falscher Eingabe. Wenn das Rendering wiederholt fehlschlägt, hören Sie auf, neu zu generieren. Beheben Sie zuerst das Quellframe oder die Parameter und reichen Sie dann erneut ein.
Eine wirksame Debugging-Reihenfolge
- Bestätigen Sie, dass die Bild-URL im Browser lädt.
- Reichen Sie eine minimale Nutzlast nur mit dem Bild ein, um Parameterprobleme zu isolieren.
- Prüfen Sie, ob die Job-ID sauber zurückgegeben wird.
- Fragen Sie zunächst manuell per Polling ab und beobachten Sie die Statusübergänge.
- Erst danach automatisieren Sie die Schleife und fügen Wiederholungsversuche für vorübergehende Netzwerkfehler hinzu.
Wenn Sie diese Schritte der Reihe nach abarbeiten, lässt sich das Problem schnell auf eine Ebene eingrenzen – Bild, Optionen oder Lebenszyklus – und die Integration bleibt in Bewegung. Nachdem Sie Anforderungsstruktur, Optionen und Polling-Ablauf verstanden haben, sind Sie bereit, gegen diesen Endpunkt zu entwickeln.
Ä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