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 :
Les paramètres du devis servent uniquement au calcul du prix. Les champs que vous envoyez à
/video/quote — y compris aspect_ratio, audio et reference_video_total_duration — sont utilisés uniquement pour calculer le prix. Ils ne sont pas transmis à /video/queue et n’influencent pas la vidéo générée. Envoyer aspect_ratio au quote est accepté même pour les modèles (tels que seedance-2-0-image-to-video) qui rejettent aspect_ratio au moment de la génération, puisque les modèles image-to-video dérivent le ratio d’aspect de sortie à partir de l’image d’entrée.Tarification reference-to-video
Pour les modèles R2V (par exemple Seedance 2.0 R2V), transmettezreference_video_total_duration — la durée cumulée en secondes de tous les clips de référence que vous prévoyez d’inclure — afin que le devis reflète le palier de tarif « input with video » et la formule de tokens (input + output) × pixels. Omettez-le et le devis renverra plutôt la valeur de base sans référence.
reference_video_total_duration n’est reconnu que par /video/quote. Il n’a aucun effet sur /video/queue et l’omettre ne provoquera pas d’erreur de génération.
Afficher des prix stables
Les devis sont ponctuels et les prix peuvent changer. Si vous souhaitez afficher un prix fixe dans votre application, appelez/video/quote une fois pour chaque combinaison de paramètres que vous prenez en charge et mettez le résultat en cache dans votre propre stockage — puis redemandez un devis selon une planification (ou lors des mises à jour de la liste de prix) pour rafraîchir la valeur en cache. Il n’existe pas d’endpoint de devis « verrouillé » ou « statique ».
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