Tutorial
So rufen Sie happyhorse-1.1/text-to-video über die HiAPI API auf: verfügbare curl- und Python-Beispiele
Anforderungsstruktur, asynchrones Polling und native Audioverarbeitung für eine funktionierende Integration
Auf dieser Seite
Was diese Integration abdeckt
Dieser Leitfaden führt Sie durch den gesamten Prozess des Aufrufs von happyhorse-1.1/text-to-video über die einheitliche HiAPI API. Nach der Lektüre verfügen Sie über eine funktionierende Anfrage: Sie übermitteln einen Text-Prompt, pollen bis zum Abschluss und speichern das generierte Video samt seiner nativen Tonspur. Zunächst stellen wir die Anforderungsstruktur vor, damit Sie die Nutzlast verstehen, bevor Sie Code schreiben; dann folgen direkt kopierbare curl-Aufrufe; anschließend erläutern wir das für die Videogenerierung erforderliche asynchrone Polling-Muster; zum Schluss übertragen wir alles nach Python und ergänzen grundlegende Fehlerbehandlung. Vorkenntnisse mit Video-APIs sind nicht nötig – Sie benötigen lediglich einen HiAPI API-Schlüssel sowie ein Terminal oder eine Python-Umgebung. Ziel ist ein minimales, aber vollständiges Integrationsbeispiel, das Sie zu Ihrer eigenen Pipeline ausbauen können.
Anforderungsstruktur von happyhorse-1.1/text-to-video
Bevor Sie einen Aufruf starten, ist es hilfreich, die Felder zu verstehen, die eine Text-zu-Video-Anfrage ausmachen. Der Endpunkt akzeptiert eine JSON-Nutzlast, die mindestens die Modellkennung und Ihren Text-Prompt enthält. Weitere gängige Felder steuern Ausgabegröße und -dauer, doch die genauen Parameternamen und zulässigen Werte entnehmen Sie bitte der Dokumentation dieses Modells auf HiAPI. Eine gültige Nutzlast sieht typischerweise so aus:
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Bei Sonnenaufgang schwenkt die Kamera langsam über einen nebligen Wald"
}
Halten Sie die Nutzlast flach und verwenden Sie ausschließlich Felder, die in der Modelldokumentation beschrieben sind. Unbekannte Felder oder falsch typisierte Werte sind die häufigste Ursache für abgelehnte Anfragen. Im Zweifel beginnen Sie mit einer minimalen Nutzlast aus nur model und prompt und fügen optionale Parameter einzeln hinzu, um Probleme einzugrenzen.
Erste Anfrage mit curl senden
Sobald die Nutzlast bereit ist, können Sie den Auftrag mit curl übermitteln. Sie senden eine POST-Anfrage mit JSON-Body und Ihrem API-Schlüssel im Authorization-Header. Die Antwort enthält in der Regel eine Kennung des Auftrags, die Sie später zum Abfragen des Status verwenden. Hier ein funktionierendes Beispiel:
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Bei Sonnenaufgang schwenkt die Kamera langsam über einen nebligen Wald"
}'
Ersetzen Sie $HIAPI_API_KEY durch Ihren tatsächlichen Schlüssel oder exportieren Sie ihn in Ihrer Shell. Die Antwort ist JSON und enthält ein id-Feld (oder eine ähnlich benannte Kennung) sowie einen Status, der die Annahme des Auftrags anzeigt. Lesen Sie die Antwort sorgfältig: Wenn der Status keinen Annahmezustand anzeigt, prüfen Sie zuerst die Fehlermeldung, bevor Sie fortfahren. Gehen Sie jetzt nicht davon aus, dass das Video bereits fertig ist; der Auftrag wurde gerade erst in die Warteschlange gestellt.
Asynchrones Polling durchführen
Die Videogenerierung erfolgt nicht sofort, daher liefert HiAPI in der ersten Antwort eine Auftragskennung statt des fertigen Videos. Sie müssen den Status-Endpunkt abfragen, bis der Auftrag einen Endzustand erreicht. Das allgemeine Muster lautet: Auftrag übermitteln, ID abrufen und dann wiederholt in kurzen Abständen den Auftragsstatus anfragen. Hören Sie auf, sobald der Status Erfolg oder Fehler anzeigt. Hier die Logik als Pseudocode:
- Auftrag übermitteln und Auftrags-
idauslesen. - Einige Sekunden warten.
- Mit dieser
idden Auftragsstatus anfragen. - Wenn der Status „completed“ oder „succeeded“ lautet, die Ausgabe-URL abrufen und die Schleife beenden.
- Wenn der Status „failed“ lautet, den Fehler protokollieren und beenden.
- Andernfalls erneut warten und wiederholen, bis eine sinnvolle maximale Anzahl an Versuchen erreicht ist.
Vermeiden Sie zu häufiges Polling. Bei Videoaufträgen reicht in der Regel ein Abstand von einigen Sekunden zwischen den Versuchen aus. Erwarten Sie außerdem nicht, dass eine einzelne blockierende Antwort das fertige Video enthält; asynchrone Modelle sind bewusst so gestaltet und bleiben bei allen lang laufenden Generierungsaufträgen konsistent.
Native Audioausgabe
Mit happyhorse-1.1/text-to-video generierte Videos enthalten von sich aus natives Audio in der Ausgabe. Wenn der Auftrag abgeschlossen ist, verweist die Antwort auf die generierte Videodatei, die bereits eine Tonspur enthält. Sie müssen das Audio nicht separat generieren oder abrufen. Um das Ergebnis zu speichern und zu überprüfen, laden Sie die Videodatei von der bereitgestellten URL herunter und behalten Sie ihr Containerformat bei. Wenn Sie die Datei programmatisch verarbeiten, prüfen Sie, ob der Audiostream vorhanden ist, beispielsweise mit einem Medienwerkzeug. Entfernen oder kodieren Sie das Audio nicht neu, es sei denn, Ihre nachgelagerte Pipeline erfordert dies, da dies die Qualität beeinträchtigen oder die Tonspur vollständig entfernen kann. Betrachten Sie die zurückgegebene Datei als vollständiges audiovisuelles Asset.
Dieselbe Anfrage in Python senden
Die Übertragung des curl-Aufrufs nach Python ist unkompliziert: Verwenden Sie dieselbe JSON-Nutzlast und ergänzen Sie eine Polling-Schleife. Das folgende Beispiel nutzt requests, wartet zwischen den Versuchen und wirft bei Fehlern eine Ausnahme. Ersetzen Sie den Endpunktpfad und die Feldnamen für den Status durch die Angaben aus der Dokumentation zu happyhorse-1.1/text-to-video auf HiAPI.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "Bei Sonnenaufgang schwenkt die Kamera langsam über einen nebligen Wald",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("Video ist bereit: ", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "Generierung fehlgeschlagen"))
time.sleep(5)
else:
raise TimeoutError("Zeitüberschreitung beim Polling")
Dies folgt der zuvor beschriebenen Logik „Pollen bis zum Abschluss“. Nutzen Sie raise_for_status(), um HTTP-Fehler frühzeitig aufzudecken, und halten Sie die Schlafintervalle sinnvoll, um unnötige Anfragen zu vermeiden.
Häufige Fehler beheben
Die meisten Integrationsprobleme lassen sich in einige Kategorien einteilen. Eine fehlerhafte Nutzlast – etwa ein fehlendes model-Feld oder ein falscher JSON-Typ – wird sofort abgelehnt; prüfen Sie Ihr JSON sorgfältig anhand der Modelldokumentation. Zu häufiges Polling kann zu Ratenbegrenzungen oder unnötiger Last führen; vergrößern Sie das Schlafintervall. Ein weiterer häufiger Fehler ist, die erste Antwort irrtümlich für das fertige Video zu halten; pollen Sie stets bis zum Endzustand. Authentifizierungsfehler bedeuten meist einen fehlenden oder falsch formatierten Authorization-Header, prüfen Sie daher, ob Ihr API-Schlüssel korrekt exportiert wurde. Wenn ein Auftrag nach dem Polling fehlschlägt, prüfen Sie abschließend die Fehlermeldung in der Statusantwort; sie weist oft auf einen ungültigen Prompt oder nicht unterstützte Parameter hin. Versuchen Sie nach der Behebung dieser Probleme erneut mit einer minimalen gültigen Nutzlast.
Ä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