Tutoriel sur l’API Veo Reference Images : des ressources à la vidéo

AI Overview

Combien d’images de référence l’API Veo peut-elle utiliser ?

Veo 3.1 accepte jusqu’à trois images de référence pour une même personne, un même personnage ou un même produit. Utilisez un petit jeu cohérent d’images qui mettent clairement en évidence l’identité, les matériaux et la forme, plutôt que trois compositions sans lien entre elles.

Les images de référence sont-elles identiques aux images initiale et finale ?

Non. Le champ referenceImages guide la cohérence du sujet ou du style, tandis que le champ image définit l’image initiale et que lastFrame contraint l’image finale. Choisissez le mode adapté selon l’élément qui doit rester fixe.

Quel modèle Veo prend-il en charge les images de référence ?

La documentation actuelle de Google sur Gemini API indique que les images de référence sont prises en charge par Veo 3.1 et Veo 3.1 Fast, mais pas par Veo 3.1 Lite ni Veo 3.0. Les générations basées sur des images de référence ont une durée fixe de huit secondes.

Que doit enregistrer une intégration API ?

Enregistrez les identifiants des ressources d’entrée, l’invite normalisée, le modèle et sa configuration, le nom de l’opération, le fichier final et le résultat de la révision. Ce suivi permet de reproduire facilement une génération ayant échoué, au lieu de transformer chaque nouvelle tentative en une série de suppositions.

Choisissez le mode d’images de référence avant de coder

Le travail pratique derrière ce tutoriel sur l’API des images de référence Veo ne se limite pas à l’envoi de données encodées en base64. Les développeurs doivent savoir quel type de contrôle visuel correspond à la séquence cible, quels champs vont ensemble, et comment réagir lorsque la sortie ignore un détail produit ou s’écarte d’un personnage.

Un nouveau concept de jeu d’images de référence créé spécifiquement pour ce guide. Le cavalier, la veste safran, les lunettes ambre et la moto cobalt constituent des repères clairs de continuité ; il ne s’agit pas d’une référence officielle Veo.

Commencez par sélectionner l’un des trois modes suivants :

Cette distinction est essentielle. Un portrait de personnage dans referenceImages constitue une indication, non une garantie que la première image rendue reproduira ce portrait pixel pour pixel. À l’inverse, une image initiale définie via image verrouille la composition de départ, mais ne fournit pas trois vues distinctes de l’identité. N’entrelacez pas ces concepts dans l’invite, puis n’accusez pas l’API d’avoir choisi la mauvaise contrainte.

Selon le tableau actuel de Google sur Gemini API, referenceImages prend en charge jusqu’à trois objets VideoGenerationReferenceImage avec Veo 3.1 et Veo 3.1 Fast. Veo 3.1 Lite ne prend pas en charge ce champ. Une requête utilisant des images de référence produit une seule vidéo, d’une durée fixe de huit secondes, compatible avec les formats paysage ou portrait, et pouvant être générée en 720p, 1080p ou 4K sur les routes complètes Veo 3.1. Une résolution plus élevée augmente la latence et le coût : validez donc le cahier des charges de la séquence avant d’augmenter l’échelle de production.

Pour une explication plus large au niveau de l’interface, avant de développer votre point de terminaison, consultez le guide Google Flow et workflow Veo.

Préparez les images de référence et l’invite

Constituez un jeu cohérent de ressources

Utilisez des références qui concordent sur l’identité. Un jeu utile de trois images pourrait comprendre une vue nette du visage et de la tenue, une vue géométrique du produit, et un petit accessoire devant impérativement être conservé. Veillez à maintenir une température de couleur, une distorsion optique et des proportions compatibles entre les images. Si une image montre une moto cobalt et une autre un châssis différent en bleu marine, l’invite ne pourra pas déterminer de façon fiable quelle géométrie est canonique.

Référence de personnage : examinez la forme du visage, la silhouette des cheveux, les panneaux de la veste et les verres ambre. Une référence lisible est plus utile qu’un portrait spectaculaire mais obscurci.

Référence de produit : la géométrie complète des roues, la silhouette du cadre, les panneaux cobalt, la veste et les lunettes sont visibles sous une lumière neutre post-pluie.

Prétraitez les images avant la requête payante. Vérifiez le type MIME, rejetez les fichiers vides, décodez une fois pour détecter toute corruption, et conservez le rapport hauteur/largeur d’origine, sauf si votre pipeline effectue intentionnellement un recadrage. Stockez une somme de contrôle et un identifiant interne de ressource. L’encodage en base64 augmente la taille de la requête : évitez donc d’encoder systématiquement des versions maîtresses trop volumineuses, quand une version dérivée correctement dimensionnée conserve tous les détails visibles.

Rédigez une invite consciente de la préservation

Une bonne invite indique à Veo ce qui se produit et ce qui doit rester stable. Utilisez cet ordre réutilisable :

Plan de suivi moyen. Le cavalier aux cheveux argentés, vêtu d’une veste safran, conduit la moto cobalt mate le long d’une route côtière mouillée à l’aube. Conservez son visage, la silhouette de sa coupe courte, ses lunettes à visière ambre, les panneaux de sa veste, la géométrie du corps de la moto, le nombre de roues et la finition cobalt. L’embrun marin évolue naturellement ; la caméra suit parallèlement sans orbiter. Sonorisation naturelle (vent, pneus, ressac lointain) ; aucune parole, aucun texte, aucun logo.Nommez les références d’après leurs caractéristiques visibles, et non d’après leurs noms de fichiers. Limitez chaque plan de huit secondes à une seule action principale et un seul mouvement de caméra. Des instructions contradictoires telles que « caméra verrouillée » et « orbite rapide » créent un problème de coordination qu’aucune image de référence ne saurait résoudre. Le guide de prompt pour la génération vidéo à partir d’images présente un modèle compact sujet-action-caméra-préservation que vous pouvez réutiliser.

Envoyez une demande Veo 3.1

Créez des références d’actifs dans JavaScript

Avec la version actuelle de @google/genai (SDK), représentez chaque image préparée sous la forme d’un objet contenant les champs imageBytes et mimeType, puis encapsulez-le avec referenceType: 'asset'. Le SDK lit la clé API depuis votre environnement ; conservez-la côté serveur, jamais dans le navigateur (JavaScript).

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

Les noms de champs peuvent varier entre les interfaces Gemini API et Vertex AI, aussi fixez explicitement la version du SDK et validez-la par rapport à la documentation officielle de l’endpoint que vous déployez effectivement. N’importe pas la structure JSON d’un wrapper tiers dans un endpoint Google. Journalisez un manifeste de requête rédigé de façon anonymisée plutôt que la charge utile base64 complète.

Utilisez la résolution 720p pour la première passe d’acceptation. Une fois validées l’identité, le mouvement, la caméra et l’audio, réexécutez la configuration approuvée à la résolution finale requise pour la livraison. Si votre application achemine les demandes vers plusieurs fournisseurs, le guide agrégateur versus API directe explique pourquoi un enregistrement de tâche normalisé est plus fiable qu’une mémoire d’interface utilisateur spécifique à un fournisseur.

Interrogez, téléchargez et stockez la sortie

La génération vidéo Veo est asynchrone. L’appel initial renvoie une opération longue durée, et non le fichier MP4 final. Interrogez l’état de l’opération à l’aide de son nom, à intervalles raisonnables, arrêtez-vous après un délai maximal défini, et conservez l’identifiant de l’opération afin qu’un redémarrage de worker puisse reprendre l’exécution plutôt que soumettre un travail en double.

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Google conserve actuellement les vidéos générées sur ses serveurs pendant deux jours : téléchargez-les donc rapidement vers un stockage sous votre contrôle. Vérifiez que le fichier existe, qu’il possède une taille non nulle, qu’il se décode correctement comme vidéo, et qu’il correspond à la durée attendue. Enregistrez une image-clé (poster frame) à des fins d’inspection, mais ne considérez jamais cette image-clé comme une preuve que l’intégralité du mouvement est propre.

Exemple vidéo cinématographique Veo 3.1 pour inspection complète de la séquence

Regardez la séquence intégrale pour évaluer la cohérence de l’identité, de l’environnement, de la caméra et de l’audio. Un fichier en mouvement met en lumière des défaillances que masque une seule image séduisante.

Validez la cohérence et gérez les échecs

Examinez à l’aide d’une grille d’acceptation fixe

Inspectez chaque sortie à vitesse normale, puis à nouveau autour du mouvement le plus complexe. Notez systématiquement « accepté », « à réviser » ou « rejeté », selon les mêmes critères à chaque fois :

Cette composition alternative modifie l’heure et le cadrage tout en conservant les mêmes ancres de continuité. Utilisez ce type d’image pour juger si l’identité de l’actif subsiste malgré un changement de scène.

Si toutes les sorties perdent la même caractéristique, la hiérarchie des références ou du prompt est probablement erronée. Si les échecs sont aléatoires, maintenez les entrées inchangées et relancez avant de tout réécrire. Si la composition doit impérativement se terminer sur une image exactement définie, privilégiez plutôt les paramètres image et lastFrame, au lieu d’ajouter davantage de langage de préservation à referenceImages.

Sortie de mouvement produit Seedance pour comparer la géométrie et le comportement contrôlé de la caméra

Il s’agit ici d’un modèle et d’un type de plan différents, inclus à titre d’exemple concret d’analyse de mouvement réel — et non comme référence-benchmark Veo. Appliquez le même cadre d’évaluation géométrique et de comportement caméra.

Distinguez clairement les erreurs liées au fournisseur des échecs créatifs. Les problèmes d’authentification, de quota, de type MIME invalide, de configuration non prise en charge, de filtrage de sécurité, de dépassement de délai ou de clip marqué comme « terminé » mais inutilisable exigent des traitements distincts. Ne relancez automatiquement que les erreurs transitoires liées au transport ou au service. Un prompt rejeté ou un résultat visuel défectueux doivent revenir à un examen humain, et non entrer dans une boucle infinie payante.Avant l’exportation finale, confirmez la fréquence de livraison avec le guide des fréquences d’images pour les vidéos IA, car la fréquence d’images générée (24 ips) et les paramètres de livraison sur la plateforme sont liées, mais ne sont pas interchangeables.

Intégrez-la dans un flux de travail Seedance Agent

L’API brute Veo convient bien lorsqu’un développeur gère déjà le stockage des ressources, la gestion des versions des prompts, l’interrogation des opérations, les validations et la stratégie de nouvelles tentatives. Seedance Agent s’avère utile lorsque la tâche réelle implique plus d’un appel : transformer un brief en liste de plans, attribuer des rôles de référence, sélectionner un modèle pris en charge pour chaque plan, examiner les résultats réels, puis relancer uniquement le segment ayant échoué.

Pour la séquence du motard, un agent peut enregistrer une fois le portrait, la moto et les lunettes ; créer un plan de suivi côtier et une fin à l’heure bleue comme deux travaux distincts ; aligner leurs règles de préservation ; et exposer les deux extraits pour validation. L’API demeure la couche de génération, tandis que l’agent gère l’état de production. Cela réduit les demandes accidentellement dupliquées et empêche qu’une modification tardive du prompt ne modifie discrètement l’ensemble canonique des ressources.

Mesurez le coût par seconde approuvée, et non par nombre de requêtes traitées. Comparez Veo 3.1 à d’autres approches en termes de stabilité d’identité, de finitions exploitables, de temps de relecture et de nombre de relances, à l’aide de la comparaison entre Seedance 2.5 et Veo 3.1. L’objectif n’est pas d’imposer systématiquement chaque plan à un seul modèle, mais de livrer une séquence cohérente avec le moins de révisions évitables possible.

Conclusion

Une intégration fiable de l’API d’images de référence Veo commence par le choix du mode de contrôle approprié, la préparation de jusqu’à trois références de ressources cohérentes, la rédaction d’un prompt clair décrivant le mouvement et la préservation, la soumission d’une requête valide Veo 3.1, la persistance de l’opération longue, le téléchargement avant l’expiration de la période de rétention, et la relecture complète de l’extrait selon une grille d’évaluation fixe. Tenez à part les nouvelles tentatives temporaires via l’API et les relances créatives, et passez à l’interpolation entre la première et la dernière image lorsque les points d’extrémité exacts comptent davantage que des indications de ressources flexibles ; lorsque le projet exige une planification de plans, des références partagées, un routage vers des modèles, des validations et des relances sélectives autour de l’appel API, démarrez le flux de travail avec Seedance Agent →