Tutorial
So verwenden Sie pixverse-v6-max/text-to-video über die HiAPI API: curl, Python und lauffähige Anfragebeispiele
Auf dieser Seite
Was dieser Endpunkt tut und wann Sie ihn verwenden
pixverse-v6-max/text-to-video ist der Text-zu-Video-Endpunkt auf HiAPI. Sie senden einen Text-Prompt, der die gewünschte Szene beschreibt, und der Endpunkt liefert ein gerendertes Video zurück. Da die Videogenerierung Zeit benötigt, ist dieser Endpunkt asynchron: Die erste Anfrage gibt nicht direkt das Video zurück, sondern eine Aufgabenkennung, mit der Sie den Fortschritt abfragen und das Endergebnis abrufen.
Dieses Muster aus „Anfrage—Bestätigung—Abfrage“ ist das zentrale mentale Modell für alle Inhalte dieses Tutorials. Der interne Ablauf ist stets gleich:
- Eine Generierungsaufgabe mit Prompt und Parametern einreichen.
- Sofort eine Aufgabenkennung erhalten.
- Diese Aufgabe abfragen, bis sie den Abschluss (oder Misserfolg) meldet.
- Die URL des Ergebnisvideos herunterladen oder einbetten.
Wann dieser Endpunkt geeignet ist
Wählen Sie pixverse-v6-max/text-to-video, wenn Ihnen nur eine Beschreibung, aber kein Quellmaterial vorliegt – zum Beispiel für Produktteaser aus einem Textbriefing, Hintergrundclips für eine App oder Storyboard-Vorschauen. Wenn Sie bereits ein Bild haben und es in Bewegung setzen möchten, gehört das zum Image-zu-Video-Workflow, nicht zu diesem Endpunkt. Wenn Sie möchten, dass das Modell den Prompt dialogisch wiederholt iteriert, ist das eine andere Interaktionsform. Dieser Endpunkt ist der direkte, einmalige Generierungspfad vom Text zum Video.
Da die Generierung asynchron ist, eignet er sich auch für warteschlangenbasierte Architekturen: Ein Web-Backend nimmt Benutzeranfragen entgegen, reicht die Aufgabe ein, und ein Worker-Prozess fragt sie ab und liefert das Ergebnis später aus. Während des gesamten Aufrufs blockiert nichts bis zum Abschluss des vollständigen Renderings.
Bevor Sie beginnen: Authentifizierung und Anfragegrundlagen
Bevor Sie Code schreiben, bestätigen Sie drei Dinge.
1. Ein API-Schlüssel
Jede HiAPI-Anfrage muss mit einem API-Schlüssel authentifiziert werden. Behandeln Sie ihn wie ein Passwort: Nicht in das Quellcode-Repository einchecken, aus Umgebungsvariablen laden und bei Offenlegung sofort rotieren. Die folgenden Beispiele lesen ihn aus HIAPI_API_KEY, daher exportieren Sie ihn zuerst in Ihrer Shell:
export HIAPI_API_KEY="your_key_here"
2. Die richtige Basis-URL
Alle Anfragen gehen an die HiAPI-API-Basis-URL, ergänzt um den Endpunktpfad. Verwenden Sie die in Ihrem HiAPI-Konto dokumentierte Basis-URL und nicht einen aus Blogartikeln fest kodierten Hostnamen – schauen Sie bei Unsicherheit in der API-Referenz im Dashboard nach. Die folgenden Beispiele verwenden $HIAPI_BASE_URL als Platzhalter für diesen Wert.
3. JSON-Konventionen
Einreichung und Statusabfrage basieren beide auf JSON über HTTPS:
- Senden Sie bei jeder Anfrage mit Body
Content-Type: application/json. - Senden Sie bei jeder Anfrage (auch bei Statusabfragen)
Authorization: Bearer $HIAPI_API_KEY. - Erwarten Sie JSON-Antworten, auch bei Fehlern – lesen Sie den Fehlerantwort-Body, nicht nur den HTTP-Statuscode.
Schneller Plausibilitätstest
Wenn Ihnen ein leichtgewichtiger Endpunkt zur Verfügung steht (z. B. eine models- oder account-Route), rufen Sie ihn einmal auf, bevor Sie den Video-Endpunkt anfassen. Ein 200 dort belegt, dass Schlüssel, Basis-URL und Header-Format korrekt sind, und schließt damit drei Variablen für das spätere Debugging aus.
Eine lauffähige curl-Anfrage
Hier ist der vollständige Einreichungsaufruf. Der Endpunktpfad ist pixverse-v6-max/text-to-video; der Body enthält Ihren Prompt und die Generierungsparameter.
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Nacht, eine regennasse Neon-Gasse, langsame Dolly-Fahrt, filmisch",
"duration": 5,
"aspect_ratio": "16:9"
}'
Feldweise Erklärung
prompt– Die Textbeschreibung. Seien Sie explizit bei Subjekt, Bewegung, Kamerafahrt und Atmosphäre. Dies ist der wichtigste Hebel für die Ausgabequalität.duration– Die angeforderte Clipdauer. Siehe den Abschnitt zu Dauer und Seitenverhältnis weiter unten.aspect_ratio– Das Ausgabebildverhältnis, z. B.16:9,9:16,1:1.
Was zurückkommt
Eine erfolgreiche Einreichung liefert ein JSON-Objekt mit einer Aufgabenkennung – dem Handle für die Abfrage. Die genauen Feldnamen entnehmen Sie der API-Referenz; in diesem Tutorial nennen wir es task_id. Speichern Sie es:
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Nacht, eine regennasse Neon-Gasse, langsame Dolly-Fahrt, filmisch","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
Beachten Sie, was die Antwort nicht enthält: das Video. Die Generierung läuft im Hintergrund. Betrachten Sie die Einreichungsantwort als Empfangsbestätigung, nicht als Ergebnis.
Die Python-Version derselben Anfrage
Die Python-Version entspricht exakt dem curl-Aufruf. Der Kürze halber verwenden wir requests, aber httpx oder urllib funktionieren ebenso – erforderlich sind nur dieselben Header und derselbe JSON-Body.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"prompt": "Nacht, eine regennasse Neon-Gasse, langsame Dolly-Fahrt, filmisch",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# Den Fehlerantwort-Body des Servers ausgeben – er nennt meist das problematische Feld
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
Wichtige Punkte zum Übernehmen
json=payloadserialisiert den Body automatisch und setzt den Inhaltstyp. Wenn Sie stattdessendata=json.dumps(payload)verwenden, müssen Sie den explizitenContent-Type-Header beibehalten.- Ein Client-Timeout beim Einreichen verhindert hängende Verbindungen. Es begrenzt nicht die Generierungszeit – die Generierung findet serverseitig statt, und genau deshalb ist Polling nötig.
- Prüfen Sie den Statuscode, bevor Sie parsen. 4xx-Antwortbodys liefern meist mehr Informationen als der Statuscode selbst; geben Sie ihn aus.
- Protokollieren Sie niemals den API-Schlüssel. Protokollieren Sie stattdessen die
task_id– sie ist sicher speicherbar und Ihr Debug-Handle.
Parameter für Dauer und Seitenverhältnis
Diese beiden Felder sind die häufigste Ursache für abgelehnte Anfragen und verdienen daher besondere Sorgfalt.
duration
duration legt die angeforderte Cliplänge in Sekunden fest. Die anforderbaren Werte sind durch den unterstützten Bereich des Endpunkts begrenzt; das Senden eines Werts außerhalb dieses Bereichs erzeugt in der Regel einen Parametervalidierungsfehler statt eines stillschweigend gekürzten Clips. Wählen Sie aus den in der API-Referenz dokumentierten unterstützten Werten und halten Sie den Wert ganzzahlig. Längere Clips benötigen länger zum Rendern, daher bevorzugen Sie in der Entwicklungsphase die kürzeste unterstützte Dauer – Sie validieren die Prozesskette, nicht die Filmkunst.
aspect_ratio
aspect_ratio ist eine Zeichenkette der Form W:H. Sie sollte dort passen, wo das Video letztlich angezeigt wird:
16:9– Querformat: Website-Hero-Bereiche, YouTube-artige Player, Desktop-Hintergründe.9:16– Hochformat: Kurzvideo-Feeds und Stories auf Mobilgeräten.1:1– Quadratisch: Rasterlayouts und Thumbnails.
Die falsche Form hier zu wählen ist billig zu beheben, aber teuer, wenn sie zu spät entdeckt wird: Ein erneutes Rendern verbraucht einen weiteren vollständigen Generierungszyklus, daher sollten Sie das Ziel-Anzeigeszenario vor dem Einreichen festlegen.
Was bei Ablehnung zu prüfen ist
- Typabweichung –
durationals Zeichenkette ("5") statt als Zahl, oderaspect_ratioals zwei Zahlen. Halten Sie duration numerisch und aspect ratio als Zeichenkette. - Nicht unterstützte Werte – Dauer oder Verhältnis außerhalb des dokumentierten Bereichs. Gleichen Sie Punkt für Punkt mit der Referenzliste ab.
- Feldbenennung – Tippfehler wie
aspectRatiooderdurationSecondswerden bestenfalls stillschweigend als unbekannte Felder behandelt. Kopieren Sie die Feldnamen aus der Referenz.
Schnelle Methode zum Eingrenzen des problematischen Felds: Reichen Sie zunächst nur mit prompt ein und fügen Sie die Parameter dann einzeln wieder hinzu. Die erste Ablehnung zeigt das problematische Feld.
Asynchrone Aufgaben abfragen, bis das Video bereit ist
Polling ist eine Schleife mit drei Regeln: Status prüfen, schlafen, bei Endzustand stoppen. Fügen Sie außerdem eine Obergrenze hinzu, damit hängende Aufgaben nicht endlos leerlaufen.
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # Status-Route siehe API-Referenz
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # sanftes Backoff mit Obergrenze
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
Warum Backoff wichtig ist
Eine Minute lang jede Sekunde konstant abzufragen, während eine Generierung läuft, verschwendet Dutzende Anfragen. Beginnen Sie mit einem kleinen Intervall und erhöhen Sie es schrittweise – der oben genannte Obergrenzen-Multiplikator pendelt sich auf ein angenehmes Intervall ein, ohne die API häufig zu belasten. Wenn Sie viele Aufgaben ausführen, ist eine Warteschlange mit einem einzelnen Polling-Worker freundlicher als eine Schleife pro Anfrage.
Ergebnisse behandeln
Nach erfolgreicher Aufgabe enthält die Antwort die Video-URL. Rufen Sie sie zeitnah ab, und wenn das Ergebnis aufbewahrt werden muss, kopieren Sie es in Ihren eigenen Speicher – signierte URLs sind nicht dauerhaft gültig. Prüfen Sie vor der Übergabe der Datei an Benutzer Inhaltstyp und Größe beim Download und protokollieren Sie die task_id zusammen mit dem gespeicherten Asset, damit sich später jedes Problem auf den exakten Generierungsdatensatz zurückführen lässt.
Häufige Fehler beheben
Wenn ein Aufruf fehlschlägt, arbeiten Sie diese Checkliste Punkt für Punkt ab. Die meisten Fehler fallen in eine der folgenden vier Kategorien.
Authentifizierung und Zugriff
- 401 / unauthorized – Schlüssel fehlt, ist falsch formatiert oder wurde nicht gesendet. Vergewissern Sie sich, dass der Header exakt
Authorization: Bearer <key>lautet und die Umgebungsvariable in der Shell oder im Prozess, der den Aufruf ausführt, tatsächlich gesetzt ist. - 403 / forbidden – Der Schlüssel ist gültig, aber der Zugriff auf diesen Endpunkt ist nicht erlaubt. Prüfen Sie die Berechtigungsbereiche des Schlüssels im Dashboard.
Anfragevalidierung
- 400 / 422 – Fehlerhaftes JSON oder falsche Feldwerte. Geben Sie den vollständigen Fehlerantwort-Body aus; er nennt meist das Feld. Prüfen Sie erneut den Typ von
durationund das Zeichenkettenformat vonaspect_ratio. - 404 beim Einreichen – Falscher Endpunktpfad. Stellen Sie sicher, dass der Pfad exakt
pixverse-v6-max/text-to-videolautet und Ihre Basis-URL kein doppeltes oder fehlendes Pfadsegment enthält.
Fehler auf Aufgabenebene
- Status
failed– Die Aufgabe wurde angenommen, aber die Generierung schlug fehl. Lesen Sie die Fehlermeldung der Aufgabe; sie unterscheidet zwischen Inhaltsablehnung und internem Fehler. Ein abgelehnter Prompt ist ein Prompt-Problem, kein API-Problem – ändern und erneut einreichen. - Hängt im laufenden Zustand – Setzen Sie eine Frist für das Polling und behandeln Sie den Timeout als einen Fehler, den Sie bearbeiten müssen, nicht als eine Ausnahme, die den Dienst abstürzen lässt.
Betriebliche Probleme
- 429 / Ratenlimit ausgelöst – Zu viele gleichzeitige Einreichungen oder Abfragen. Reduzieren Sie die Parallelität und beachten Sie etwaige Wiederholungshinweise in der Antwort.
- Verbindungs-Timeout beim Einreichen – Netzwerk- oder Proxy-Problem, kein Generierungsproblem. Wiederholen Sie die Einreichung mit Backoff, aber nur wenn Sie mögliche doppelte Aufgaben tolerieren können.
- Video-URL 404 beim Download – Die URL ist abgelaufen. Rufen Sie das Aufgabenergebnis erneut ab, statt die alte URL wiederzuverwenden.
Eine wiederholbare Gewohnheit
Protokollieren Sie bei jedem Fehler drei Werte: den HTTP-Statuscode, den Antwortbody und (falls vorhanden) die task_id. Diese drei verwandeln „es ist kaputt“ in „es ist hier kaputt“, und das ist der einzige Schlüssel, um Debugging zu beschleunigen.
Wie es weitergeht
Sie beherrschen jetzt den vollständigen Kreislauf: Authentifizierung, Einreichen, Aufgabenkennung erhalten, Polling mit Backoff und Abrufen des Ergebnisses. Für den Produktionseinsatz können Sie Einreichen und Polling in eine kleine Client-Klasse kapseln, task_id und Prompt zusammen mit jedem Asset für die Rückverfolgbarkeit speichern und das Polling in einen Hintergrund-Worker verlagern, damit benutzerseitige Anfragen nie durch das Rendering blockiert werden.
Als Nächstes können Sie benachbarte Endpunkte in der HiAPI-Referenz erkunden – Image-zu-Video, um vorhandene Standbilder zu animieren, sowie den dialogischen Prompt-Iterationsmodus, um den Bildstil zu verfeinern, bevor Sie die vollständige Generierung starten. Die hier erlernte Anfrageform lässt sich nahezu unverändert übertragen.
Ä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