API de génération de vidéo à partir de texte Grok : appeler le modèle vidéo grok-imagine via hiapi

Pourquoi choisir d'appeler la génération vidéo Grok via une API agrégée

La génération vidéo est rarement un problème de modèle unique. Vous partez d'une idée, puis il vous faut rapidement une variante moins chère pour les brouillons, un modèle de plus haute fidélité pour les versions finales, et une solution de repli lorsque l'état d'un fournisseur se dégrade. Intégrer chaque cas en direct signifie maintenir des identifiants, des formats de requête et des sémantiques d'erreur séparés — un travail sans aucun rapport avec la vidéo que vous voulez générer.

hiapi propose une interface unifiée pour les modèles de génération de vidéo à partir de texte Grok. Vous ne conservez qu'un seul jeu d'identifiants et une seule convention de requête, et grok-imagine/text-to-video comme grok-imagine-1.5-lite se trouvent sous le même groupe de points de terminaison. Changer de variante ne demande que de modifier le nom du modèle, sans réécrire l'intégration : vos modèles de prompts, votre logique de nouvelle tentative et votre gestion des ressources restent inchangés.

Il existe aussi une raison opérationnelle. L'accès agrégé signifie que la disponibilité et la dépréciation des modèles sont gérées en amont, de sorte que les nouvelles variantes de grok-imagine entrent dans votre pipeline sans redéploiement. Pour les équipes qui livrent des fonctionnalités vidéo dans un produit, cela réduit votre périmètre de responsabilité : vous ne êtes responsable que des prompts et de l'expérience produit, sans avoir à vous soucier de l'infrastructure sous-jacente du fournisseur.

Découvrir les variantes de modèles : grok-imagine/text-to-video et grok-imagine-1.5-lite

hiapi propose deux variantes de génération de vidéo à partir de texte Grok, situées à des points différents de la courbe d'arbitrage entre fidélité et débit.

grok-imagine/text-to-video

Il s'agit du modèle général de génération de vidéo à partir de texte. Choisissez-le lorsque la qualité de sortie est prioritaire : clips principaux, supports marketing, propositions conceptuelles, et tout cas où le mouvement sera examiné attentivement. C'est le choix par défaut le plus sûr lorsque vous ne savez pas encore comment un prompt se comportera, car vous l'évaluez alors dans les meilleures conditions du modèle.

grok-imagine-1.5-lite

La variante lite vise à réduire la latence et la consommation de ressources. Utilisez-la pour les boucles d'itération — exploration de prompts, aperçus de storyboard, génération par lots de clips candidats — lorsque vous voulez d'abord converger vers un prompt avant de payer le coût d'une génération onéreuse. En production, elle peut aussi servir des scénarios à forte concurrence et à faible risque, où une réponse rapide compte plus qu'une image parfaite.

Comment choisir

Une règle pratique : utilisez grok-imagine-1.5-lite pour les brouillons et grok-imagine/text-to-video pour les versions finales. Comme les deux partagent la même convention de requête sur hiapi, vous pouvez paramétrer le nom du modèle côté client et basculer selon le niveau de tâche. Si le brouillon généré par lite semble déjà bon, promouvez le même prompt vers le modèle complet pour produire le livrable. Sinon, vous avez économisé une tentative lente et coûteuse.

La composition d'une requête de génération de vidéo à partir de texte

Chaque appel de génération de vidéo à partir de texte que vous envoyez via hiapi se compose d'un petit nombre d'éléments. Les comprendre séparément rend le débogage beaucoup plus rapide.

Le champ model

L'identifiant de modèle sélectionne la variante (grok-imagine/text-to-video ou grok-imagine-1.5-lite). Traitez-le comme une configuration, et non comme une chaîne codée en dur enfouie dans une fonction — vous aurez besoin plus tard de router par niveau.

Le prompt

Le prompt est l'entrée créative principale. Il doit décrire le sujet, l'action, la scène et le style par ordre d'importance. Une scène sans action n'est qu'une image ; c'est la proposition d'action qui en fait une vidéo. Nous détaillerons plus loin la structure des prompts.

Le mode de mouvement

Le mode de mouvement guide la manière dont le modèle interprète les déplacements de caméra et de sujet. C'est le paramètre le plus souvent négligé, et aussi celui qui le plus souvent produit une sortie « qui semble incorrecte » malgré un bon prompt. Faites-le correspondre à ce que décrit votre prompt, plutôt que de conserver la valeur par défaut.

Sortie et livraison

La génération vidéo est asynchrone. L'appel renvoie une tâche, que vous suivez jusqu'à son achèvement, puis vous récupérez la ressource générée via sa référence. Comme le rendu prend du temps réel, votre client doit gérer explicitement la période d'attente — interrogation périodique ou vérification d'achèvement de type webhook — plutôt que de supposer une réponse en ligne. La facturation est calculée à la seconde de sortie ; gardez donc l'intention de durée en tête dès le premier brouillon.

Choisir un mode de mouvement cohérent avec le prompt

Le mode de mouvement est un a priori fort. Il indique au modèle vers quel type de mouvement pencher avant même qu'il n'analyse les détails plus fins de votre prompt. Lorsque le mode et le prompt sont incohérents, la sortie tend à faire des compromis et ne satisfait ni l'un ni l'autre.

Faire correspondre le mode au mouvement dominant

Si votre prompt décrit un mouvement de caméra — travelling avant lent, travelling latéral, orbite autour du sujet —, choisissez un mode de mouvement orienté caméra. Si votre prompt décrit un sujet qui se déplace dans une image globalement statique — une personne qui marche, de la fumée qui s'élève, de l'eau qui coule —, choisissez un mode orienté mouvement du sujet. Si le clip doit ressembler à un plan fixe mais avec une légère vitalité, choisissez l'option la plus sobre.

Un seul mouvement dominant par clip

Un clip qui tente d'accomplir à la fois un mouvement de caméra, une action du sujet et une transition de scène en quelques secondes paraîtra généralement confus. Choisissez le mouvement unique le plus important, réglez le mode qui le soutient, et laissez le prompt décrire les détails secondaires sans ajouter de verbes de mouvement concurrents. Si vous avez besoin d'une séquence composite, générez des clips séparés puis montez-les ensemble.

Itérer d'abord sur le mode, puis réécrire le prompt

Lorsque le résultat semble incorrect mais que le sujet et le style sont bons, changez d'abord le mode de mouvement. C'est moins coûteux en expérimentation que de réécrire un long prompt, et cela permet d'isoler si le problème vient de l'interprétation du mouvement ou de la description du contenu.

Une requête fonctionnelle, décomposée étape par étape

Le flux ci-dessous est la forme générale d'une tâche de génération de vidéo à partir de texte Grok sur hiapi. Les noms de paramètres dans la charge utile suivent le schéma de requête du point de terminaison ; consultez la référence de l'API pour l'ensemble exact de champs avant la mise en production.

Étape 1 : construire la charge utile

Partez d'un objet structuré plutôt que d'une concaténation de chaînes, afin de pouvoir le journaliser et le réutiliser.

{
  "model": "grok-imagine/text-to-video",
  "prompt": "Au crépuscule, un cerf-volant rouge s'élève sur une plage balayée par le vent, la caméra monte lentement, douce lumière dorée",
  "motion_mode": "<mode correspondant au mouvement de caméra vers le haut>"
}

Étape 2 : soumettre la tâche

Envoyez la charge utile au point de terminaison de génération de vidéo à partir de texte, avec vos identifiants hiapi dans l'en-tête d'autorisation. La réponse renvoie un identifiant de tâche et un statut. Persistez immédiatement cet identifiant — c'est le handle de toutes vos opérations suivantes.

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Étape 3 : interroger l'achèvement

Le rendu est asynchrone. Interrogez le statut de la tâche à intervalles avec backoff, et arrêtez-vous lorsque la tâche signale un état terminal. Traitez « pending » et « processing » comme des états normaux, et non comme des erreurs.

Étape 4 : récupérer la ressource

Une fois la tâche terminée, la réponse contient une référence vers la vidéo générée. Téléchargez-la dans votre propre stockage plutôt que de faire un lien direct vers une URL temporaire, afin que votre produit ne dépende pas de la durée de vie des artefacts générés.

Étape 5 : journaliser les entrées

Journalisez le modèle, le prompt, le mode de mouvement et l'identifiant de tâche avec la ressource stockée. Lorsqu'un clip sera plus tard jugé bon ou mauvais, vous aurez besoin des entrées exactes pour le reproduire ou le corriger.

Rédiger des prompts que les modèles vidéo peuvent réellement exécuter

Un prompt vidéo est une description de plan, pas une planche d'ambiance. Le modèle a besoin d'instructions concrètes et physiquement plausibles pour les animer dans la dimension temporelle.

Utiliser un ordre de propositions stable

Sujet, action, scène, caméra, style. Cet ordre place l'essentiel en premier et donne une hiérarchie claire lorsque le modèle doit arbitrer entre détails et cohérence. Gardez le même ordre dans votre modèle pour pouvoir comparer les résultats de manière significative.

Une action, exprimée par un verbe

« Un cycliste » est une image fixe. « Un cycliste pédale dans une montée » est un clip. Énoncez explicitement l'action et gardez-la unique. Si vous voulez un mouvement secondaire, ajoutez-le comme détail d'appui — « pédale dans une montée, maillot flottant » — plutôt que comme une seconde action concurrente.

Décrire le mouvement de caméra en langage simple

Indiquez ce que fait la caméra : monter, panoramique à gauche, rester stable. Évitez les formulations vagues comme « angle dynamique » qui peuvent signifier n'importe quoi. Plus l'instruction de caméra est claire, mieux elle s'accorde avec le mode de mouvement choisi.

Contraindre le style, pas les spécifications

Décrivez l'éclairage, la palette et la texture (« douce lumière dorée, couleurs douces, léger grain »). Évitez d'inventer des paramètres techniques que le modèle n'expose pas — la résolution et la durée sont des réglages de requête, pas du contenu de prompt. Les mélanger embrouille le modèle et les développeurs qui lisent les journaux.

Maintenir une bibliothèque de modèles

Conservez quelques squelettes de prompts pour chaque cas d'usage — plans produit, paysages, moments de personnage — en laissant des emplacements pour le sujet et l'action. Les modèles rendent les sorties plus cohérentes et permettent d'attribuer plus facilement un échec à la seule variable modifiée.

Renforcer l'intégration pour la production

Le premier appel réussi est la partie facile. Ce qui distingue une démo d'un produit, c'est le comportement de l'intégration lorsque les tâches sont lentes, que les prompts sont rejetés ou que le trafic explose.

Traiter la génération comme une file d'attente

Ne bloquez jamais une requête utilisateur en attendant le rendu vidéo. Soumettez la tâche, renvoyez l'identifiant de tâche au client, et laissez un worker interroger l'achèvement puis pousser le résultat lorsqu'il est prêt. Cela découple la latence de votre requête de celle du rendu et vous permet de réessayer sans redemander l'utilisateur.

Réessayer avec backoff, et uniquement sur les échecs réessayables

Les erreurs transitoires et les expirations justifient un backoff exponentiel avec jitter. Les erreurs de validation — prompt mal formé ou champ non pris en charge — échoueront de la même manière à chaque fois ; présentez ces erreurs à l'appelant plutôt que de gaspiller des tentatives. Classez explicitement les erreurs dans le code client.

Hiérarchiser les modèles

Routez les brouillons vers grok-imagine-1.5-lite et les versions finales vers grok-imagine/text-to-video. Comme la facturation est calculée à la seconde de sortie, le niveau brouillon est l'endroit où vous maîtrisez les dépenses : convergez vers un prompt à faible coût, puis promouvez-le. Limitez le nombre de tâches simultanées par utilisateur pour éviter les boucles de génération incontrôlées.

Versionner les prompts

Stockez les prompts avec une étiquette de version et consignez quelle version a produit quelle ressource. Lorsque vous modifiez un modèle, vous pouvez comparer avec les sorties précédentes et annuler les régressions, plutôt que de deviner.

Valider les ressources, sinon les écarter

Avant de présenter une vidéo à un utilisateur, exécutez des contrôles légers sur la vidéo récupérée — intégrité du fichier, durée attendue, contenu non vide. Une étape de validation peu coûteuse évite qu'un lecteur corrompu n'apparaisse devant le client et vous indique qu'une variante de modèle se comporte anormalement.

Avec un seul point de terminaison, deux niveaux de modèles et des modes de mouvement choisis avec soin, l'API de génération de vidéo à partir de texte Grok s'intègre proprement dans un pipeline de production. Commencez par un seul prompt sur grok-imagine/text-to-video, faites fonctionner la boucle de bout en bout, puis ajoutez le niveau lite pour l'itération.