Passer au contenu principal
La génération vidéo est asynchrone. Soumettez une tâche, enregistrez le queue_id, puis interrogez /video/retrieve jusqu’à ce que la réponse soit video/mp4.

Endpoints

Étape 1 : Mettre en file d’attente la génération

Requête :
Réponse (200) :
Pour les modèles Grok Imagine Private, la réponse de mise en file d’attente inclut un champ supplémentaire download_url :
download_url est une URL pré-signée que vous utilisez pour télécharger la vidéo finie au lieu de la lire depuis la réponse retrieve. Elle n’est renvoyée qu’une seule fois dans la réponse de mise en file d’attente, alors persistez-la à côté du queue_id. Cela s’applique aux quatre variantes Grok Imagine Private :
  • grok-imagine-text-to-video-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
Contrairement aux variantes publiques grok-imagine-*-video, les modèles Grok Imagine Private ne sont pas facturés pour les rejets dus à la modération de contenu, donc vous ne payez que pour les générations réussies. Enregistrez model, queue_id et download_url (s’il est présent) pour tous les appels ultérieurs.

Liens de téléchargement privés

Pour les modèles privés, download_url est la manière de récupérer le fichier fini une fois la tâche terminée. Le lien est éphémère et à usage unique : il sert à vous livrer le MP4, pas à servir d’URL durable ou largement partagée. Si un téléchargement est interrompu, vous pouvez réessayer le même GET plusieurs fois depuis le même environnement jusqu’à ce que le fichier soit terminé. Ces nouvelles tentatives servent à récupérer après des coupures réseau — pas à sonder le même lien indéfiniment, le partager entre de nombreux clients ou l’intégrer comme une URL média permanente. De tels schémas se manifestent souvent sous forme de 429 ou de 410, ce qui peut surprendre si vous vous attendiez à ce que le lien se comporte comme un hébergement de fichier classique. Pour plus de fiabilité, les requêtes GET doivent provenir d’un seul réseau client. Une certaine souplesse est possible si votre IP change une fois (par exemple si vous déconnectez un VPN et réessayez), mais une large variation des IP sources ne fonctionnera généralement pas. L’URL reste valide jusqu’à 24 heures, ou jusqu’à ce que l’objet soit supprimé.
Si vous avez besoin d’une URL stable, d’une lecture publique ou d’un accès répété dans le temps, enregistrez d’abord le fichier dans votre propre stockage et servez-le à partir de là.
Confidentialité : révoquer le lien avec DELETE Lorsque vous avez fini de récupérer le fichier — ou si vous décidez de ne pas le conserver — vous pouvez appeler DELETE sur la même download_url. Aucune clé API Venice n’est requise pour cette requête. C’est facultatif mais recommandé lorsque la confidentialité importe, car certains proxys et middleboxes en dehors de Venice conservent des journaux des URL complètes, et supprimer le lien est le moyen le plus simple de réduire la fenêtre pendant laquelle l’URL pré-signée existe.
Flux : interrogez /video/retrieve jusqu’à COMPLETEDGET la download_url (réessayez légèrement si le transfert échoue) → enregistrez le fichier où nécessaire → DELETE la download_url si vous souhaitez invalider le lien → optionnellement, appelez /video/complete si vous utilisez toujours le nettoyage basé sur la file d’attente.

Étape 2 : Sonder jusqu’à la fin

Requête :
La réponse dépend du statut : Réponse de traitement (200, application/json) :
Les durées sont en millisecondes. Utilisez average_execution_time pour estimer l’attente restante. Réponse terminée (200, video/mp4) : Le corps de la réponse contient des données vidéo binaires brutes. Enregistrez-les dans un fichier. Réponse terminée (200, application/json avec "COMPLETED") : Pour les modèles qui ont renvoyé une download_url au moment de la mise en file d’attente, retrieve renvoie toujours du JSON. Récupérez la vidéo avec GET download_url (sans en-tête d’authentification). Voir Liens de téléchargement privés pour comprendre comment ces URL fonctionnent, les nouvelles tentatives et le DELETE optionnel.

Étape 3 : Nettoyage (optionnel)

Soit auto-suppression à la récupération :
Soit appel à /video/complete après enregistrement :
Réponse (200) :

Exemple complet


Paramètres de la requête

Requête Queue

La validation de la mise en file d’attente est spécifique au modèle. Vérifiez /models?type=video pour les champs de requête pris en charge par chaque modèle avant d’appeler /video/queue.

Requête Quote

Requête Retrieve

Requête Complete


Image to Video

Pour les modèles image-to-video, transmettez l’image source via image_url. Le prompt décrit le mouvement souhaité, pas le contenu de l’image.
Ou avec base64 :

Devis de prix

Obtenez le coût exact avant la génération. Envoyez uniquement les entrées de tarification (model, duration, et optionnellement resolution, aspect_ratio, audio) : Requête :
Réponse :
Le devis est en USD.

Erreurs


Stratégie de sondage

  1. Sondez /video/retrieve à intervalle régulier (par exemple, toutes les 5 secondes)
  2. Si le Content-Type est application/json et que le status est "PROCESSING", attendez et sondez à nouveau. Utilisez average_execution_time et execution_duration (millisecondes) pour estimer le temps restant
  3. Si le Content-Type est video/mp4, enregistrez le corps de la réponse comme fichier de sortie
  4. Si le Content-Type est application/json et que le status est "COMPLETED", faites un GET sur la download_url depuis la réponse queue pour récupérer la vidéo (voir Liens de téléchargement privés)
  5. Si vous avez utilisé download_url, envisagez un DELETE sur cette URL lorsque vous avez terminé pour réduire la durée d’existence de l’URL pré-signée ; puis définissez optionnellement delete_media_on_completion: true sur retrieve ou appelez /video/complete pour un nettoyage basé sur la file d’attente
  6. Traitez 404 comme un média invalide, expiré ou supprimé ; traitez 500/503 avec des nouvelles tentatives/backoff

Modèles disponibles

Voir Modèles vidéo pour la liste actuelle des modèles et la tarification.