Flux de travail de vidéo courte avec références utilisant vidu-q4-preview sur l'API HiAPI

Pourquoi la génération de vidéo par références transforme les flux de travail de vidéo courte

La génération à partir de simples prompts exige du modèle qu'il invente tout de lui-même : apparence du sujet, vêtements, composition, mouvement et audio. Pour une expérimentation ponctuelle, cela convient. Pour la production de vidéos courtes — où le même personnage ou présentateur doit apparaître dans des dizaines de clips — le contrôle par simple prompt s'effondre rapidement. Une infime variation de formulation produit une dérive visuelle massive, et aucune ingénierie de prompt ne peut fixer de manière fiable un visage, une tenue ou une voix.

La génération de vidéo par références change cet accord. Vous ne décrivez plus le sujet par des mots ; vous fournissez au modèle un ensemble de matériaux de référence — plusieurs images qui établissent l'identité, plus une référence vocale qui établit la voix du sujet — et laissez le prompt décrire ce qui doit se passer, plutôt que qui est à l'image. Le contrôle créatif passe de la formulation au niveau des tokens à la curation au niveau des matériaux ; la préparation des matériaux devient la première étape d'ingénierie du flux de travail, et non un ajout après coup.

Ce changement s'aligne parfaitement sur la façon dont le contenu de vidéo courte est réellement produit :

• Identité réutilisable. Un ensemble de références validé peut être réutilisé sur plusieurs clips, de sorte qu'une série conserve sa cohérence visuelle sans avoir à re-prompter.
• Séparation des préoccupations. Le scénariste gère l'action et le rythme dans le prompt ; le responsable des matériaux gère l'apparence et la voix dans l'ensemble de références.
• Entrées auditables. Lorsque la sortie semble erronée, vous pouvez comparer les ensembles de références entre exécutions, plutôt que de deviner quel adjectif a modifié le résultat.

La vidéo courte élève aussi le seuil du coût d'échec. La distribution de clips coûte peu, le tournage à nouveau coûte cher ; un pipeline capable de produire une variation prévisible à partir d'une bibliothèque de références fixe a donc plus de valeur qu'un pipeline qui produit occasionnellement d'excellents résultats ponctuels. La génération de vidéo par références est précisément le mécanisme qui rend cette prévisibilité possible.

Ce qui reste inchangé

Vous devez toujours rédiger des prompts, soumettre des requêtes de type asynchrone et post-traiter la vidéo renvoyée. La différence est que les matériaux de référence deviennent des entrées de première classe, que vous devez versionner, valider et stocker comme les prompts.

Comment le modèle de référence vidu-q4-preview s'intègre dans HiAPI

Sur HiAPI, vidu-q4-preview/reference-to-video sert d'identifiant de modèle, adressé dans la même interface de requête que celle utilisée pour vos autres tâches de génération. Vous n'avez pas besoin d'intégrer un SDK fournisseur distinct, ni de gérer un second jeu d'identifiants. Votre application appelle l'API HiAPI, la plateforme achemine la requête vers le modèle de génération de vidéo par références, et la réponse renvoie les matériaux vidéo générés.

Cette couche présente un intérêt pratique à deux titres :

1. Interface d'intégration unique. Authentification, structure de requête et traitement des erreurs restent cohérents entre les modèles que vous utilisez ; ajouter ou changer de modèle devient donc une modification de configuration, et non un nouveau client.
2. Outils d'exploitation unifiés. Journalisation, nouvelles tentatives, gestion du débit et analyse des réponses sont centralisés en un seul endroit, évitant que le chemin de la génération de vidéo par références ne devienne une base de code parallèle.

Usage de ce point de terminaison

Le modèle de génération de vidéo par références convient aux clips où l'identité du sujet doit être ancrée par les matériaux fournis, plutôt qu'inventée à partir du texte — clips promotionnels courts, segments de présentateur fixe, plans produits avec un mannequin cohérent, et contenus similaires nécessitant une cohérence de série. Ce n'est pas un éditeur vidéo universel ; il génère de nouveaux clips à partir de vos références et de votre prompt.

Traiter l'identifiant de modèle comme une configuration

L'identifiant de modèle et les paramètres qu'il prend en charge évoluent au fil du temps, à mesure que des modèles sont ajoutés, prévisualisés et retirés. Ne codez pas en dur vidu-q4-preview/reference-to-video dans la logique métier à une douzaine d'endroits. Conservez-le dans une couche de configuration et vérifiez, avant publication, l'identifiant actuel, les paramètres pris en charge et la forme d'entrée attendue dans la documentation publique de HiAPI. Tout ce que ce guide dit de la structure des requêtes est un aperçu de la forme ; la documentation est la source d'autorité pour les noms de champs exacts.

Ce que ce guide ne couvre pas

La tarification est volontairement hors périmètre. La facturation sur HiAPI est mesurée par tâche en fonction du modèle et des paramètres que vous soumettez ; les chiffres en temps réel appartiennent au panneau de prix de la plateforme, et non à un tutoriel qui deviendrait obsolète. Il en va de même pour toute affirmation sur la latence ou le débit d'un modèle donné — mesurez-les sur votre propre charge de travail, plutôt que de faire confiance à des chiffres copiés d'un article de blog.

Préparer des références multi-images et vocales

La qualité des références domine la qualité de la sortie. Consacrez un véritable temps d'ingénierie à la préparation des matériaux, car la cohérence du modèle ne peut être meilleure que les références que vous fournissez.

Choisir des références multi-images

Utilisez plusieurs images montrant le même sujet dans des conditions différentes mais compatibles — angles variés, éclairage légèrement différent, mélange de gros plans et de plans moyens. L'objectif est de donner au modèle une couverture suffisante pour résoudre l'identité sous plusieurs points de vue sans introduire de contradictions.

Règles de sélection pratiques :

• Même sujet, même période. Évitez de mélanger des références d'apparence qui diffèrent par la coiffure, la barbe ou le style, sauf si vous souhaitez que le modèle fasse une moyenne.
• Traitement des couleurs cohérent. Des écarts trop importants de balance des blancs ou d'étalonnage entre références poussent le modèle vers une palette instable.
• Aucun sujet concurrent. Un ensemble de références contenant deux visages proéminents risque de provoquer un mélange. Un sujet par ensemble.
• Résolution suffisante. Des références réduites ou fortement compressées perdent les détails précis dont le modèle a besoin.

Préparer une référence vocale

La référence vocale établit le timbre et le mode d'expression. Fournissez un audio propre — faible bruit de fond, pas de musique de fond, pas de locuteurs qui se chevauchent. Découpez le passage le plus représentatif du mode d'expression souhaité, et gardez-le assez court pour être représentatif, plutôt qu'un monologue complet. Si vous prévoyez de produire une série avec la même voix, verrouillez une référence vocale et réutilisez-la.

Normaliser les matériaux

Avant que tout matériau n'atteigne le constructeur de requêtes, faites-le passer par une étape de normalisation : format et dimensions d'image cohérents au sein d'un ensemble, format audio et fréquence d'échantillonnage cohérents. La normalisation élimine toute une classe de pannes du type « ça marchait hier » et donne un sens aux clés de cache.

Versionner les ensembles de références

Traitez les ensembles de références comme des artefacts dotés d'identifiants :

refsets/
  presenter-a/
    v1/  images/  voice.wav  manifest.json
    v2/  images/  voice.wav  manifest.json

Le manifeste doit consigner la provenance des matériaux, la normalisation appliquée et le hachage de chaque fichier. Lorsque la sortie dérive, vous pouvez immédiatement déterminer si l'ensemble de références a changé. Lorsqu'elle dérive alors que l'ensemble de références est inchangé, vous savez qu'il faut examiner le prompt ou la version du modèle. Gardez les ensembles de références petits — quelques images soigneusement choisies valent mieux qu'un empilement incohérent volumineux — et gardez-les versionnés, car la reproductibilité est l'essentiel.

Assembler la requête dans la base de code

Une requête d'appel de génération de vidéo par références comporte trois parties conceptuelles : la sélection du modèle, le prompt décrivant l'action, et la charge de références contenant les matériaux multi-images et vocaux. Gardez chaque partie dans sa propre couche, afin que modifier l'une n'oblige pas à toucher les autres.

Structure opérationnelle

config/          id du modèle, point de terminaison, paramètres par défaut
refsets/         matériaux de référence versionnés + manifeste
builder/         assemble prompt + ensemble de références + paramètres en requête
client/          appel HiAPI, nouvelles tentatives, mappage des erreurs
handler/         valide et stocke la vidéo renvoyée

Le constructeur de requêtes de cette forme effectue approximativement les opérations suivantes :

1. Charger l'identifiant de modèle depuis la configuration (par exemple vidu-q4-preview/reference-to-video), jamais depuis un littéral enfoui dans l'appelant.
2. Charger l'ensemble de références par version depuis le manifeste, afin que les matériaux exacts utilisés soient consignés avec l'exécution.
3. Joindre le texte du prompt décrivant la scène, l'action et le rythme.
4. Fusionner les paramètres par défaut avec toute surcharge propre à l'exécution.
5. Produire un objet de requête, soumis à l'API HiAPI par la couche client.

Garder les jointures propres

Le constructeur est le seul endroit qui connaît la forme de la requête. Si un nom de champ change, ou si le modèle de génération de vidéo par références ajoute un paramètre, la modification se fait dans le constructeur, et non ailleurs. Le texte du prompt doit être un modèle avec des emplacements de contenu variables (nom du produit, étapes de la scène, appel à l'action), et non une concaténation de chaînes dispersée dans le code appelant.

Valider avant d'envoyer

Échouez rapidement dans le constructeur : vérifiez que l'ensemble de références est analysable, que le nombre attendu d'images est présent, que l'audio n'est pas vide et que le prompt respecte les limites. Une requête mal formée rejetée localement prend quelques millisecondes ; la même requête rejetée à distance exige un aller-retour et, selon la façon dont vous mesurez, peut générer une tâche échouée.

Consigner la provenance

Pour chaque tâche soumise, consignez l'identifiant de modèle, la version de l'ensemble de références, la version du modèle de prompt et toute surcharge de paramètres. Cette ligne de journal est la clé qui transforme « la sortie s'est dégradée » en question à laquelle on peut répondre. Vérifiez les identifiants et noms de paramètres actuels dans la documentation publique de HiAPI lors de l'intégration, et revérifiez lors d'une montée de version du modèle.

Traiter la réponse et le post-traitement de vidéo courte

Les matériaux renvoyés sont un point de départ, pas un livrable final. Les plateformes de vidéo courte imposent leurs propres formats d'image, durées, normes de sonie et conventions de sous-titres ; la vidéo renvoyée et son audio natif doivent être adaptés à ces exigences.

Stocker d'abord, transformer ensuite

Avant de toucher à la vidéo brute renvoyée, écrivez-la dans un stockage persistant. La transformation est destructive et parfois défectueuse ; si la seule copie est celle qui a été recadrée, un mauvais recadrage signifie une régénération. Utilisez l'id de tâche plus la version de l'ensemble de références comme clé de l'objet stocké, afin de pouvoir remonter de tout clip publié à ses entrées.

Chaîne de post-traitement

Une chaîne typique de vidéo courte ressemble à ceci :

• Inspection. Lisez la durée, les dimensions, la fréquence d'images et la sonie audio des matériaux renvoyés, et consignez-les dans les métadonnées de la tâche.
• Découpe. Coupez à la durée cible, en choisissant délibérément les points d'entrée et de sortie, plutôt qu'en coupant à un décalage fixe — la génération laisse souvent un temps d'instabilité au début.
• Recadrage. Redimensionnez et recadrez au format d'image de la plateforme. Si le sujet est décentré, utilisez un recadrage conscient du sujet plutôt qu'une coupe centrée à l'aveugle.
• Normalisation audio. Appliquez une normalisation de sonie à la piste audio native et vérifiez que la référence vocale se maintient comme prévu.
• Sous-titres et image de marque. Ajoutez les sous-titres incrustés ou les incrustations comme étape séparée, afin qu'ils puissent être modifiés sans réencoder la vidéo de base.
• Encodage. Produisez un profil final pour chaque plateforme cible, en conservant le master intermédiaire.

Traiter explicitement l'audio

Si le modèle renvoie de l'audio natif, traitez la piste audio comme un artefact indépendant. Extrayez-la, mesurez-la, normalisez-la, puis réencapsulez-la. Cela corrige une piste trop faible sans relancer la génération, et rend les problèmes de synchronisation visibles tôt.

Alerter bruyamment en cas d'échec de validation

Après traitement, exécutez des contrôles automatiques : durée dans la plage, format d'image correct, audio présent et au-dessus du seuil de sonie, pas d'images noires au début. Tout ce qui échoue entre en file de revue plutôt qu'en distribution. Le volume de la vidéo courte rend impossible la revue humaine de chaque clip, le point de contrôle de validation est donc essentiel pour empêcher des sorties médiocres d'être publiées.

Liste de contrôle des coûts, de la latence et des modes de défaillance

La génération est mesurée par tâche et consomme du temps réel ; les préoccupations d'exploitation sont donc les mêmes que pour toute tâche asynchrone coûteuse : comment éviter de gaspiller des exécutions, et comment diagnostiquer une exécution échouée ? Utilisez la liste de contrôle ci-dessous lors du dépannage d'une exécution de génération de vidéo par références échouée.

Causes liées aux entrées

• L'ensemble de références est-il analysable, et est-ce la version souhaitée ?
• Les images sont-elles cohérentes quant au sujet, au style et au traitement des couleurs ?
• La référence vocale est-elle propre, sans musique ni chevauchement de voix, et non vide ?
• Les dimensions, formats et fréquences d'échantillonnage respectent-ils les limites de la documentation ?

Causes liées à la requête

• L'identifiant de modèle est-il orthographié exactement comme dans la documentation, et toujours valide ?
• Les noms de paramètres et types de valeurs sont-ils valides pour ce modèle ?
• Le prompt respecte-t-il la limite de longueur, et décrit-il l'action plutôt que de redécrire l'identité déjà couverte par les références ?
• Avez-vous dépassé une limite de concurrence ou de débit imposée par votre propre couche client ?

Causes liées à la réponse

• La requête a-t-elle réussi mais renvoyé des matériaux échouant au point de contrôle de validation ? Vérifiez d'abord la découpe et la stabilité du début du clip ; une fenêtre de génération plus longue corrige souvent les clips qui commencent en milieu d'action.
• La sortie s'écarte-t-elle du modèle par rapport aux références ? C'est presque toujours un problème de cohérence des références, et non de prompt.
• Observez-vous des délais d'attente sporadiques ? Ajoutez un suivi idempotent des tâches, afin que les nouvelles tentatives ne deviennent pas des doubles facturations.

Hygiène des coûts et de la latence

• Ne réessayez pas aveuglément. Ne réessayez qu'en cas d'erreur de transport ou d'état explicitement réessayable. Un échec de contenu échouera à nouveau.
• Validez les entrées localement. Chaque erreur détectée localement est une exécution que vous n'avez pas payée.
• Mesurez vous-même la latence. Enregistrez le temps entre soumission et disponibilité, par modèle et jeu de paramètres, sur votre propre charge de travail, plutôt que de supposer un chiffre.
• Cachez agressivement. Une sortie validée peut servir de nombreuses variantes en aval ; régénérez la base uniquement lorsque les références ou la scène changent réellement.
• Limitez la portée d'impact. Les tâches par lots doivent avoir un seuil maximal d'échecs, arrêtant la file en cas de défaillance systémique.

Gardez cette liste à côté des journaux. La plupart des exécutions échouées se classent en moins d'une minute dans l'une des trois branches ci-dessus.

Intégrer le tout dans un pipeline reproductible

La dernière étape consiste à transformer le flux de travail en boucle, générant à la demande des clips de vidéo courte à partir de modèles et d'une bibliothèque de références, chaque sortie validée étant réinjectée dans la bibliothèque.

La boucle

Le pipeline comporte quatre phases exécutées de manière répétée :

1. Sélection du modèle + des références. Le modèle conserve le squelette du prompt, les valeurs par défaut des paramètres et la configuration de post-traitement. La bibliothèque de références conserve les ensembles de matériaux versionnés. Une tâche associe un modèle à un ensemble.
2. Génération. Le constructeur de requêtes assemble l'appel, le client le soumet, et les matériaux renvoyés arrivent dans le stockage avec les métadonnées de provenance.
3. Revue et post-traitement. Les clips passent automatiquement le point de contrôle de validation ; tout ce qui est signalé passe en revue humaine. Les clips approuvés poursuivent par la découpe, le recadrage, la normalisation audio et l'encodage.
4. Rétroaction. Les notes structurées issues de la revue — « dérive de la voix », « éclairage incohérent » — deviennent des modifications de la bibliothèque de références ou du modèle, plutôt que des retouches ad hoc du prompt. Incrémentez le numéro de version afin que les modifications restent traçables.

Ce qui le rend reproductible

• Des modèles plutôt que des prompts. Tout ce qui se répète d'une tâche à l'autre appartient au modèle, et non au code d'exécution.
• Versionnez tout. Ensembles de références, modèles, identifiants de modèle, configuration de post-traitement. Le journal des tâches doit vous permettre de reconstruire précisément ce qui a été exécuté.
• Empaquetage déterministe. Construisez la file à partir de données — tableur de scènes, calendrier éditorial — afin que le pipeline les étende en tâches.
• La revue comme donnée. Consignez les résultats de revue dans un stockage structuré, afin de pouvoir mesurer quels modèles et ensembles de références produisent le plus de clips approuvés.

Par où commencer

Commencez par un modèle et un ensemble de références, exécutez un petit lot, ajustez l'ensemble de références avant de passer à l'échelle. La valeur du pipeline vient de l'effet cumulatif de la bibliothèque de références dans le temps : chaque clip approuvé valide les matériaux qui le sous-tendent, chaque clip rejeté indique précisément ce qui doit être corrigé.

Lorsque vous serez prêt à intégrer, vérifiez l'identifiant de modèle actuel et la forme de requête dans la documentation HiAPI concernant vidu-q4-preview/reference-to-video, et gardez la sélection du modèle dans la configuration, afin que le reste du pipeline survive à la prochaine version de modèle.