Tutorial
Muse-video-1.0/text-to-video über die HiAPI API aufrufen: curl- und Python-Leitfaden
Anfragefelder, asynchrones Polling und lauffähige Beispielanfragen
Auf dieser Seite
Vor dem Senden: Authentifizierung, Endpunkt und Modellkennung
muse-video-1.0/text-to-video wandelt Text-Prompts in generierte Videoclips um. Sie senden einen Prompt und einige Steuerparameter, der Dienst rendert den Clip und gibt anschließend eine herunterladbare URL oder Referenz zurück.
Der entscheidende architektonische Punkt: Dieser Aufruf ist asynchron. Das Rendern von Videos dauert lange, und die API hält Ihre HTTP-Verbindung nicht offen, bis die Datei fertig ist. Der Ablauf besteht daher aus zwei Phasen:
- Einreichen – Sie senden den Prompt und die Parameter per POST. Die Antwort kommt schnell zurück und enthält eine Auftragskennung sowie den anfänglichen Auftragsstatus.
- Polling – Sie fragen den Auftrag anhand der Kennung in Intervallen per GET ab, bis sein Status einen Endzustand erreicht (Erfolg oder Fehler), und rufen dann das Ergebnis ab.
Dieses Muster „erst einreichen, dann abfragen“ ist der wichtigste Punkt, den Sie verinnerlichen sollten, bevor Sie Code schreiben. Es verändert die Struktur Ihrer Anwendung: Das Video erscheint nicht in der Antwort auf die Einreichungsanfrage, und jeder Fehler, auf den Sie stoßen, gehört zu einer bestimmten Phase – Einreichung, Validierung, Rendering oder Abruf. Diese Phasen in Ihrem eigenen Code zu trennen (durch separate Funktionen und getrennte Protokollierung) erleichtert die Anwendung des restlichen Leitfadens.
Die übergebene Modellzeichenkette muss exakt lauten: muse-video-1.0/text-to-video. Die Form vendor/model ist die allgemeine Konvention der Modellendpunkte von HiAPI, und anhand dieser leitet das API-Routing ab, welcher Generator aufgerufen wird.
Die Anfrage aufbauen: Prompt, Dauer und Audiofelder
Vor der ersten Anfrage müssen drei Dinge bereitstehen.
API-Schlüssel
Jede Anfrage muss per Bearer-Token authentifiziert werden. Bewahren Sie ihn in einer Umgebungsvariable statt im Quellcode auf, damit er nicht in Commit-Verläufen auftaucht:
export HIAPI_API_KEY="your_key_here"
Senden Sie ihn im Header Authorization: Bearer $HIAPI_API_KEY. Wenn eine Anfrage due to einen Authentifizierungsfehler fehlschlägt, prüfen Sie zuerst diesen Header – die häufigsten Ursachen sind ein Tippfehler im Variablennamen, ein Leerzeichen am Ende oder ein Wert, der in der aktuellen Shell nicht gesetzt ist.
Basis-URL
Alle Aufrufe verwenden dieselbe Basis-URL der HiAPI-Plattform. Verwenden Sie den aktuellen Wert aus Ihrem Kontopanel oder der API-Referenz und kopieren Sie ihn nicht aus älteren Code-Snippets. Speichern Sie ihn in einer Variable, sodass Sie ihn nur an einer Stelle ändern müssen.
Modellkennung
Die Modellzeichenkette lautet muse-video-1.0/text-to-video. Behandeln Sie sie als literalen, groß-/kleinschreibungssensitiven Wert. Fügen Sie keine Varianten zusammen und raten Sie nicht, etwa durch andere Groß-/Kleinschreibung oder fehlende Suffixe – eine unbekannte Modellkennung führt zu einem Validierungsfehler, nicht zu einem Fallback.
Sobald diese drei Elemente bereitstehen, können Sie den Anfragekörper erstellen.
Ein funktionierender curl-Aufruf
Der Anfragekörper ist JSON. Konzeptionell enthält er drei Feldgruppen.
Prompt
Der Prompt ist die kreative Anweisung und bestimmt den Großteil der Ausgabequalität. Ein wirksamer Prompt beschreibt konkret Motiv, Handlung, Kamerabewegung, Beleuchtung und Stil, statt nur Adjektive aneinanderzureihen. Es handelt sich um ein einfaches Zeichenkettenfeld.
Dauer
Ein Text-to-Video-Modell muss wissen, wie lang der Clip sein soll. Die Dauer ist ein Anfragefeld und beeinflusst die Kosten: Die Generierung wird nach Ausgabesekunden abgerechnet. Da der zulässige Bereich und der Standardwert vom Modell zu einem bestimmten Zeitpunkt definiert werden, lesen Sie den exakten Feldnamen und die erlaubten Werte aus der aktuellen API-Referenz für muse-video-1.0/text-to-video und raten Sie nicht. Eine Dauer außerhalb des Bereichs führt zu einem Validierungsfehler.
Audio
muse-video-1.0/text-to-video unterstützt neben der visuellen Generierung auch audiobezogene Steuerungen. Auch diese sind Anfragefelder – üblicherweise Schalter oder Eingaben im Stil eines Audio-Prompts –, deren genaue Namen und zulässigen Werte in derselben API-Referenz dokumentiert sind. Bei der ersten Integration ist es ratsam, die optionalen Audiofelder zunächst vollständig wegzulassen, zu bestätigen, dass ein Video erfolgreich zurückgegeben wird, und erst dann die Audiooptionen schrittweise hinzuzufügen.
Der minimale Anfragekörper sieht daher ungefähr so aus (Feldnamen nur als Beispiel – bitte anhand der Referenz bestätigen):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "Eine langsame Luftaufnahme gleitet bei Sonnenaufgang über einen nebligen Kiefernwald, weiches Volumenlicht, filmisch",
"duration": 5
}
Da sich Parametersätze weiterentwickeln können, ist es eine verlässliche Gewohnheit, die Referenzdokumentation des Modells abzurufen, Feldnamen wörtlich zu übernehmen und vor dem Senden lokal zu validieren.
Dieselbe Anfrage in Python
Der Einreichungsaufruf ist ein HTTP-POST. Der genaue Ressourcenpfad wird durch die HiAPI-API-Referenz definiert; das folgende Beispiel verwendet den üblichen Auftrags-Endpunkt, wobei das Modell im Anfragekörper steht.
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "Ein Papproboter läuft durch eine regnerische Neonstraße, Spiegelungen auf nassem Asphalt, 35mm-Film-Look",
"duration": 5
}'
Die Antwort ist klein und kommt schnell zurück. Wichtig darin sind die Auftragskennung und der Status. Eine typische Struktur sieht so aus:
{
"id": "job_abc123",
"status": "queued"
}
Notieren Sie die id – sie ist der Referenzwert für alle weiteren Aufrufe. Ein status von queued oder processing ist normal und bedeutet, dass die Anfrage angenommen wurde und kein Problem vorliegt.
Manuelles Polling in der Shell:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Führen Sie dies in Abständen einige Male aus, um zu beobachten, wie sich status in Richtung Endzustand verändert. In der Praxis sollte diese Schleife in Ihrem Code stehen, nicht in der Terminal-Historie.
Asynchrone Ergebnisse verarbeiten und pollen, ohne die API zu überlasten
Die Python-Version erledigt dieselben beiden Dinge – einreichen, dann pollen –, ergänzt aber Timeout-Behandlung, begrenzte Wiederholungen und Ergebnis-Speicherung, damit sie unbeaufsichtigt sicher laufen kann.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"Ein gläsernes Miniatur-Ökosystem auf einem Holztisch, Morgenlicht, schwebende Staubpartikel, Makro",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
Hier gibt es drei bewusste Entscheidungen. Wiederholungen werden durch eine Frist begrenzt, nicht durch die Anzahl der Schleifendurchläufe, sodass der Prozess nicht unbegrenzt hängen bleibt. Der Backoff wächst bei vorübergehenden Fehlern und bei Erfolgspfad-Polling nur langsam. Der Download ist eine separate Streaming-Anfrage, wodurch große Dateien nicht über den JSON-Pfad laufen.
Häufige Fehler und ihre Fehlerbehebung
Die Polling-Frequenz ist eine echte Designentscheidung. Alle 200 Millisekunden zu pollen erzeugt nur unnötige Last; alle fünf Minuten zu pollen verschwendet reale Zeit, nachdem das Rendering abgeschlossen ist.
Eine praktische Strategie:
- Beginnen Sie mit einem moderaten Intervall (einige Sekunden) und erhöhen Sie es schrittweise – eine Multiplikation mit 1,5 pro Polling, gedeckelt bei etwa einer halben Minute, funktioniert gut.
- Erhöhen Sie den Backoff bei
429- und5xx-Antworten: Verdoppeln Sie das Intervall und wiederholen Sie, und behandeln Sie sie als Kapazitätssignal, nicht als Auftragsstatus. - Legen Sie eine maximale Gesamtwartezeit fest und werfen Sie bei Überschreitung einen Fehler, statt ewig zu pollen. Renderings mit längerer Dauer dauern tatsächlich länger, daher sollte die Obergrenze auf Ihre eigene Arbeitslast abgestimmt sein.
- Protokollieren Sie Übergänge nur einmal bei Statusänderungen, nicht bei jedem Polling – laute Logs machen echte Fehler schwer erkennbar.
Die Antwort eines abgeschlossenen Auftrags enthält normalerweise einen Endzustand status, die Auftrags-id und eine Ergebnisnutzlast mit einer herunterladbaren Video-URL, manchmal mit Metadaten und Ablaufzeit der URL. Rufen Sie die Datei nach Erfolg zeitnah ab. Wenn der Auftrag failed meldet, lesen Sie die Fehlermeldung in der Antwort, bevor Sie es erneut versuchen – ein Validierungsfehler wird nie durch Wiederholen erfolgreich, ein interner Rendering-Fehler hingegen kann es werden.
Nächste Schritte
Beginnen Sie mit dem minimalen Anfragekörper, bestätigen Sie einen erfolgreichen End-to-End-Lauf und fügen Sie dann Dauer- und Audiosteuerungen gemäß der aktuellen Referenzdokumentation für muse-video-1.0/text-to-video hinzu. Dasselbe Muster „erst einreichen, dann abfragen“ lässt sich auf andere Modellendpunkte von HiAPI übertragen, sodass der hier geschriebene Client-Code wiederverwendbar ist.
Ä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