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 :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-privategrok-imagine-image-to-video-privategrok-imagine-reference-to-video-privategrok-imagine-video-to-video-private
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à.
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.
/video/retrieve jusqu’à COMPLETED → GET 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 :
Réponse de traitement (200, application/json) :
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 :/video/complete après enregistrement :
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 viaimage_url. Le prompt décrit le mouvement souhaité, pas le contenu de l’image.
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 :
Erreurs
Stratégie de sondage
- Sondez
/video/retrieveà intervalle régulier (par exemple, toutes les 5 secondes) - Si le
Content-Typeestapplication/jsonet que lestatusest"PROCESSING", attendez et sondez à nouveau. Utilisezaverage_execution_timeetexecution_duration(millisecondes) pour estimer le temps restant - Si le
Content-Typeestvideo/mp4, enregistrez le corps de la réponse comme fichier de sortie - Si le
Content-Typeestapplication/jsonet que lestatusest"COMPLETED", faites unGETsur ladownload_urldepuis la réponse queue pour récupérer la vidéo (voir Liens de téléchargement privés) - Si vous avez utilisé
download_url, envisagez unDELETEsur cette URL lorsque vous avez terminé pour réduire la durée d’existence de l’URL pré-signée ; puis définissez optionnellementdelete_media_on_completion: truesur retrieve ou appelez/video/completepour un nettoyage basé sur la file d’attente - Traitez
404comme un média invalide, expiré ou supprimé ; traitez500/503avec des nouvelles tentatives/backoff