Zum Hauptinhalt springen
Die Videogenerierung ist asynchron. Sende einen Job, speichere die queue_id und pollte /video/retrieve, bis die Antwort video/mp4 ist.

Endpoints

Schritt 1: Generierung in die Queue stellen

Request:
Antwort (200):
Für Grok-Imagine-Private-Modelle enthält die Queue-Antwort ein zusätzliches Feld download_url:
download_url ist eine vorsignierte URL, mit der du das fertige Video herunterlädst, statt es aus der Retrieve-Antwort zu lesen. Sie wird nur einmal in der Queue-Antwort zurückgegeben – persistiere sie also zusammen mit der queue_id. Das gilt für alle vier Grok-Imagine-Private-Varianten:
  • grok-imagine-text-to-video-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
Im Gegensatz zu den öffentlichen grok-imagine-*-video-Varianten werden Grok-Imagine-Private-Modelle bei Inhalts-Moderation-Ablehnungen nicht berechnet – du zahlst also nur für erfolgreiche Generierungen. Speichere model, queue_id und ggf. download_url für alle weiteren Aufrufe. Bei Private-Modellen ist download_url der Weg, die fertige Datei abzuholen, sobald der Job fertig ist. Der Link ist kurzlebig und zweckgebunden: Er soll dir das MP4 ausliefern und nicht als langfristige oder breit geteilte URL dienen. Wenn ein Download abbricht, kannst du denselben GET ein paar Mal aus derselben Umgebung wiederholen, bis die Datei fertig ist. Diese Retries sind für Netzwerk-Hänger gedacht – nicht dafür, denselben Link unbegrenzt zu pollen, ihn auf viele Clients zu verteilen oder ihn wie eine permanente Medien-URL einzubetten. Solche Muster zeigen sich oft als 429 oder 410, was überraschend sein kann, wenn du den Link wie reguläres File-Hosting erwartet hast. Für Zuverlässigkeit sollten GET-Anfragen aus einem Client-Netzwerk kommen. Etwas Flexibilität gibt es, wenn sich deine IP einmal ändert (z. B. VPN trennen und erneut versuchen), aber starke Variation der Quell-IPs funktioniert in der Regel nicht. Die URL bleibt bis zu 24 Stunden lang gültig oder bis das Objekt entfernt wird.
Wenn du eine stabile URL, öffentliche Wiedergabe oder wiederholten Zugriff über die Zeit brauchst, speichere die Datei zuerst in deinem eigenen Storage und liefere sie von dort aus.
Privacy: Link mit DELETE widerrufen Sobald du die Datei abgeholt hast – oder wenn du sie nicht behalten willst – kannst du DELETE auf denselben download_url aufrufen. Für diesen Request ist kein Venice-API-Schlüssel nötig. Das ist optional, aber bei datenschutzrelevanten Fällen empfohlen, weil einige Proxies und Middleboxen außerhalb von Venice vollständige URLs loggen, und das Löschen des Links ist der einfachste Weg, das Zeitfenster der vorsignierten URL zu verkleinern.
Flow: /video/retrieve pollen bis COMPLETEDGET auf den download_url (bei Abbruch leicht retrien) → Datei dort speichern, wo du sie brauchst → optional DELETE auf den download_url → optional /video/complete aufrufen, falls du Queue-basiertes Cleanup nutzt.

Schritt 2: Auf Fertigstellung pollen

Request:
Die Antwort hängt vom Status ab: Processing-Antwort (200, application/json):
Zeiten in Millisekunden. Nutze average_execution_time zur Abschätzung der verbleibenden Wartezeit. Complete-Antwort (200, video/mp4): Response-Body ist rohes Binär-Video. In Datei speichern. Complete-Antwort (200, application/json mit "COMPLETED"): Für Modelle, die beim Queue-Eintrag eine download_url geliefert haben, liefert Retrieve immer JSON. Hol das Video per GET download_url (ohne Auth-Header). Siehe Private Download-Links für Details, Retries und optional DELETE.

Schritt 3: Cleanup (optional)

Entweder automatisch beim Abruf löschen:
Oder nach dem Speichern /video/complete aufrufen:
Antwort (200):

Vollständiges Beispiel


Request-Parameter

Queue-Request

Die Queue-Validierung ist modellspezifisch. Prüfe /models?type=video für die unterstützten Request-Felder pro Modell, bevor du /video/queue aufrufst.

Quote-Request

Retrieve-Request

Complete-Request


Image-to-Video

Bei Image-to-Video-Modellen das Quellbild per image_url übergeben. Der Prompt beschreibt die gewünschte Bewegung, nicht den Bildinhalt.
Oder mit Base64:

Preis-Quote

Exakte Kosten vor der Generierung. Nur die Pricing-Inputs senden (model, duration und optional resolution, aspect_ratio, audio): Request:
Antwort:
Das Quote ist in USD.

Fehler


Polling-Strategie

  1. /video/retrieve in einem Intervall pollen (z. B. alle 5 Sekunden)
  2. Wenn Content-Type application/json und status "PROCESSING" ist: warten und erneut pollen. average_execution_time und execution_duration (Millisekunden) zum Schätzen der Restzeit nutzen
  3. Wenn Content-Type video/mp4 ist: Response-Body als Output-Datei speichern
  4. Wenn Content-Type application/json und status "COMPLETED" ist: GET auf den download_url aus der Queue-Antwort, um das Video abzuholen (siehe Private Download-Links)
  5. Wenn du download_url genutzt hast: Erwäge DELETE auf diese URL, wenn du fertig bist, um das Zeitfenster der vorsignierten URL zu verkürzen; dann optional delete_media_on_completion: true bei Retrieve setzen oder /video/complete für Queue-basiertes Cleanup aufrufen
  6. 404 als ungültiges, abgelaufenes oder gelöschtes Media behandeln; 500/503 mit Retries/Backoff abfangen

Verfügbare Modelle

Aktuelle Modellliste und Preise unter Video-Modelle.