API Runway de génération de vidéo à partir de texte : guide du développeur pour appeler Gen-4.5 via hiapi

Pourquoi utiliser un point de terminaison hébergé de génération de vidéo à partir de texte

La génération de vidéo à partir de texte n'est pas un substitut au pipeline de génération ou d'édition d'images : c'est une capacité fondamentale différente. Un modèle d'image vous donne une image fixe, que vous pouvez recadrer, retoucher ou composer. Un appel de génération de vidéo à partir de texte vous donne du mouvement : mouvement de caméra, action du sujet et lumière qui évolue dans le temps. Si votre produit a besoin d'un clip vidéo — une courte séquence marketing, une boucle d'arrière-plan intégrée à l'application, un aperçu d'une scène — un seul appel « de la requête au clip » est souvent le chemin le plus rapide de l'idée à l'élément.

Le prix à payer est le contrôle. Vous décrivez le mouvement avec des mots, plutôt que de le fixer avec des images-clés, le modèle doit donc l'interpréter lui-même. Cela rend la qualité du prompt plus importante que dans les tâches d'image, et la boucle d'itération plus importante qu'une tentative unique.

Le point de terminaison hébergé fourni par hiapi élimine le travail d'infrastructure autour de cette capacité fondamentale : vous obtenez une interface cohérente, un modèle d'identifiants, et une structure de réponse unifiée entre les modèles vidéo que vous appelez. Vous passez votre temps sur les prompts et l'intégration produit, plutôt que sur les pipelines de stockage, l'interrogation des tâches et les SDK de chaque fournisseur.

Cas d'usage appropriés :

• Des clips courts générés à la demande à partir des entrées utilisateur ou de modèles
• Une exploration rapide de concepts avant d'investir dans un pipeline de production complet
• Des éléments d'arrière-plan et de B-roll qui restent utilisables même si une génération présente un léger défaut

Cas non appropriés : tout besoin de continuité précise image par image, de sortie déterministe ou de cohérence narrative sur une longue durée. Prévoyez un budget pour plusieurs clips candidats par résultat exploitable.

Structure du point de terminaison runway-gen-4.5/text-to-video

Conceptuellement, une requête envoyée à runway-gen-4.5/text-to-video se compose de trois parties : le prompt, les réglages au niveau de la requête, et votre identité/autorisation. Seule la première est créative ; les deux autres déterminent comment le modèle s'exécute et comment la facturation est calculée.

Ce que vous envoyez

• La chaîne de prompt. L'entrée créative principale — décrivez en langage naturel le sujet, l'action, le cadrage, la lumière et l'ambiance.
• Les réglages au niveau de la requête. Le ratio d'aspect, la durée, et tout indicateur de génération exposé par le point de terminaison. Ceux-ci déterminent la forme du conteneur de sortie, pas son contenu.
• L'en-tête d'authentification. Votre clé hiapi, à fournir à chaque appel. Traitez-la comme un secret ; ne la publiez jamais dans du code client.

Ce que vous recevez

La génération vidéo n'est pas instantanée, donc selon la façon dont le point de terminaison est appelé, vous pouvez recevoir un handle de tâche à interroger, ou une réponse qui se résout en une URL de média. Dans les deux cas, vous recevez une référence vers un clip généré, et non des octets bruts en ligne. Si vous devez continuer à utiliser l'élément au-delà de la durée de validité de l'URL renvoyée, téléchargez-le et persistez-le dans votre propre stockage.

Un modèle mental utile : le point de terminaison est une fonction qui mappe (prompt, settings) vers un clip plus des métadonnées. Votre intégration doit le traiter comme asynchrone, rejouable et non déterministe — les mêmes entrées ne produisent pas toujours le même clip, c'est le comportement attendu, pas un défaut.

Gardez la construction des requêtes simple et ennuyeuse. Écrivez une petite enveloppe interne qui assemble le corps de la requête, ajoute l'authentification, envoie l'appel, et normalise la réponse en { status, videoUrl, error }. Toutes les sections suivantes de ce guide supposent que cette enveloppe existe déjà.

Rédiger des prompts cinématographiques qui tiennent en mouvement

Les adjectifs vagues s'effondrent en mouvement. « A beautiful cinematic shot of a city » ne donne au modèle rien d'animable, il génère donc quelque chose de générique et flottant. La solution est d'être explicite sur les quatre éléments dont un cadreur a besoin : le sujet, le cadrage, la lumière et le mouvement.

Nommer le sujet et l'action

Indiquez ce qui est à l'image et ce que cela fait tout au long du clip. Donnez un point de départ et un point d'arrivée implicite, afin que le modèle ait une trajectoire de mouvement à suivre.

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

Spécifier explicitement le cadrage

Utilisez un langage de cadrage que le modèle peut associer à un mouvement : avancée lente, plan large fixe, suivi caméra à l'épaule, travelling en contre-plongée, panoramique lent vers la droite, descente aérienne. Un seul mouvement de caméra par clip est plus sûr que trois mouvements en conflit.

Static wide shot, camera at ground level, no zoom.

Spécifier la lumière et l'heure

La lumière détermine la majeure partie du niveau de production perçu. Indiquez la source et la texture : lumière du jour diffuse par temps couvert, fort soleil d'après-midi venant de la gauche du cadre, néons réels dans des reflets mouillés nocturnes.

Décrire un mouvement physiquement crédible

Un mouvement rapide dans un clip court produit du flou. Préférez une action unique et lisible à vitesse modérée à de nombreux événements rapides. Si vous voulez de la tension, obtenez-la du mouvement de caméra et de la lumière, plutôt qu'en faisant se dérouler une douzaine d'événements simultanément.

Tenir en un paragraphe

Un paragraphe compact de une à trois phrases l'emporte sur une liste à puces de spécifications. Écrivez-le comme une description de plan, pas comme une liste de souhaits. Évitez d'empiler les adjectifs de style ; choisissez un rendu et tenez-vous-y.

Un modèle fiable :

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

Réécrivez votre prompt dans ce modèle avant de modifier le moindre réglage.

Une requête exécutable, étape par étape

Cette démonstration suppose Node.js et une fonction d'enveloppe, mais la structure ne dépend pas du langage.

Étape 1 : écrire le plan

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

Étape 2 : choisir les réglages de la requête

Choisissez un ratio d'aspect correspondant à l'endroit où le clip sera finalement utilisé, ainsi que la durée la plus courte qui raconte l'histoire. Les clips courts échouent vite et coûtent moins cher à explorer.

Étape 3 : envoyer l'appel

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

Étape 4 : récupérer le clip

Si la réponse contient un handle de tâche, interrogez-la avec un intervalle de backoff croissant jusqu'à ce qu'elle atteigne un état terminal. Si elle contient directement une URL de média, passez à l'étape 5.

Étape 5 : persister l'élément

Téléchargez le clip et stockez-le avec vos propres clés. Traitez l'URL renvoyée comme une adresse temporaire.

Étape 6 : consigner les points de décision

Enregistrez ensemble le prompt, les réglages et l'élément généré. C'est ce journal qui rend la section suivante — l'ajustement — exploitable, plutôt que fondée sur des suppositions.

Ajuster la sortie sans modifier le prompt

Lorsqu'un clip déçoit, le réflexe est de réécrire le prompt. Retenez-vous pendant un tour. Le prompt et les réglages sont des variables indépendantes, et changer les deux en même temps détruit votre capacité à juger lequel était décisif.

Isoler les variables

Gardez le prompt fixe et ne modifiez qu'un seul réglage au niveau de la requête — ratio d'aspect, durée ou un indicateur de génération. Relancez. Si le clip s'améliore, le problème était structurel plutôt que créatif. Sinon, revenez sur ce réglage et modifiez plutôt le prompt.

Résoudre les problèmes structurels avec les réglages

• La composition ne correspond pas au placement ? Changez le ratio d'aspect.
• L'action est tronquée avant d'être achevée ? Augmentez la durée.
• Tout flotte sans point d'ancrage ? Raccourcissez le clip pour qu'il n'ait pas le temps de flotter.

Résoudre les problèmes de contenu en modifiant le prompt

• Sujet erroné ou absent ? Nommez-le plus tôt et rendez-le spécifique.
• Caméra qui dérive ? Supprimez tout vocabulaire de cadrage sauf le seul mouvement que vous voulez.
• Plat et sans vie ? Ajoutez une source de lumière et une direction.

Faire un petit test A/B

Figez un prompt de référence, générez trois variantes en modifiant une seule proposition chacune. Comparez-les côte à côte, pas de mémoire. Le non-déterminisme signifie qu'un seul mauvais clip n'est pas une preuve ; avant de conclure qu'une proposition est nuisible, cherchez une tendance sur deux ou trois exécutions.

Consignez vos conclusions dans le journal que vous tenez déjà. Après une douzaine d'itérations, cela devient un manuel de prompts et de réglages propre à votre produit, bien plus précieux que n'importe quelle liste générique de prompts.

Déboguer les échecs courants

La plupart des échecs de la première semaine se rangent dans quatre catégories. Chacune a un chemin d'investigation différent.

Requête rejetée ou bloquée

Une réponse non 2xx avec un message de politique signifie que le prompt ou les réglages n'ont pas été acceptés. Lisez le corps de la réponse d'erreur, plutôt que de réessayer à l'aveugle. Réécrivez la description problématique, retirez les personnes réelles ou marques nommées, puis renvoyez. Consignez le prompt rejeté tel quel — les rejets répétés remontent souvent à une habitude dans votre modèle de prompt.

Délais d'attente

La génération vidéo est lente. Si votre client HTTP expire avant que le point de terminaison ne réponde, la tâche peut toujours être en cours et être facturée. Augmentez le délai d'attente du client pour les appels de génération, et déplacez l'interrogation dans un worker en arrière-plan plutôt que de garder la requête en attente.

Clips vides ou inutilisables

Une réponse réussie mais un clip sans sujet reconnaissable signifie généralement que le prompt était trop abstrait. Relisez-le par rapport au modèle sujet-cadrage-lumière-mouvement. Si l'un des quatre éléments manque, c'est votre point de correction.

Erreurs d'authentification et de configuration

401 et 403 signifient un problème de clé, pas un problème de prompt. Vérifiez que la clé existe dans l'environnement d'exécution, pas seulement dans votre shell local, et vérifiez le format de l'en-tête. Ces échecs coûtent d'autant moins cher qu'ils sont détectés tôt, et d'autant plus cher qu'ils sont détectés en production.

Une règle générale : classez l'erreur avant de modifier quoi que ce soit. Les erreurs de prompt, les erreurs de réglage et les erreurs d'infrastructure nécessitent des corrections différentes ; les mélanger gaspille le budget de génération.

Coûts, latence et garde-fous de production

Avant la mise en ligne, décidez du comportement du point de terminaison en cas d'échec, car la génération vidéo est l'appel le plus coûteux et le plus lent de la plupart des produits.

Budgéter par clip, pas par appel

La facturation vidéo est généralement liée à la longueur de la sortie, donc les clips longs coûtent plus cher que les courts. Budgétez en unités de clips finis — y compris les nouvelles tentatives et les candidats rejetés — plutôt qu'en comptant les appels API. Fixez des limites de génération par utilisateur et par session. Consultez le panneau de tarification pour les tarifs actuels ; ne les codez pas en dur dans la logique métier.

Concevoir pour la latence

Ne bloquez jamais une requête destinée à l'utilisateur sur une génération. Lancez la tâche, renvoyez immédiatement un handle, et livrez le clip par interrogation, webhook ou notification. Affichez la progression dans l'UI, pour qu'un rendu lent se lise comme un travail en cours plutôt que comme un blocage. Mettez en cache les clips générés par prompt et réglages, pour éviter de redemander une régénération.

Valider avant de générer

Des vérifications peu coûteuses avant l'appel épargnent un traitement coûteux après :

• imposez une longueur minimale et maximale de prompt dans votre enveloppe
• rejetez les prompts dépourvus de sujet ou d'action
• validez le ratio d'aspect par rapport à la cible de rendu
• confirmez que l'utilisateur est dans son quota

Modérer à l'entrée et à la sortie

Effectuez un contrôle textuel du prompt avant l'envoi. Effectuez un contrôle léger du clip renvoyé avant l'affichage. Les deux coûtent moins cher qu'un incident de support.

Conserver un plan de repli

Si la génération échoue ou prend trop de temps, proposez une image de couverture statique ou un clip de remplacement, plutôt qu'une erreur. La fonctionnalité doit se dégrader, pas s'interrompre.

Commencez par un point de terminaison, une enveloppe et un journal ; ajoutez progressivement des garde-fous au fur et à mesure que vous découvrez où votre produit échoue réellement, et laissez le panneau de tarification rester la source unique de vérité pour les coûts.