Ajouter du texte à une vidéo via l'API : workflows de sous-titres et d'incrustations

Pourquoi le texte sur une vidéo est un problème de conception d'API, et pas seulement de prompt

Ajouter du texte à une vidéo générée peut ressembler à une simple ligne de prompt à modifier : décrire le sous-titre, envoyer la requête, récupérer un clip avec du texte. Mais en pratique, dès que vous avez besoin que les sous-titres soient lisibles, synchronisés, localisables ou réutilisables entre les scènes, le prompt cesse d'être la partie intéressante. L'architecture le devient.

Deux voies praticables existent, et elles mènent à des bases de code différentes :

• Texte natif à la génération. Vous demandez au modèle vidéo de rendre le texte comme partie intégrante de la scène. Une requête, un asset, aucun post-traitement.
• Asset propre plus incrustations. Vous générez d'abord un asset sans texte (ou demandez une composition sans texte), puis vous composez les sous-titres et les incrustations dans une seconde étape de rendu.

Pourquoi est-ce plus qu'une question d'esthétique ? Parce que tout ce qui est en aval dépend de ce choix. Si le texte est présent dans les pixels générés, vous ne pouvez pas facilement le restyler, le traduire, l'aligner temporellement sur la parole ou corriger une faute de frappe sans régénérer le clip. Si le texte vit dans une incrustation séparée, vous maîtrisez la mise en page, la police et la synchronisation, mais vous devez désormais posséder un moteur de rendu et ajouter une requête à votre pipeline.

Le reste de ce guide traite le texte sur vidéo comme ce qu'il devient généralement en production : un problème de données (quel texte, où, quand) plus un problème de rendu (qui le dessine). Une fois les deux séparés, les appels API deviennent simples, et vous pouvez changer de backend de génération sans réécrire votre logique de sous-titres.

Un modèle mental utile est de toujours distinguer trois choses : le contenu (le texte lui-même), la synchronisation (quand il apparaît) et la présentation (police, position, style). La génération native compresse les trois en une étape opaque. Les incrustations gardent les trois explicites et modifiables. Aucune n'est universellement meilleure ; l'objectif est de savoir à laquelle vous vous engagez avant d'écrire l'intégration.

Voie un : le texte natif à l'écran via le prompt au moment de la génération

Le texte natif signifie que le modèle de génération dessine les caractères dans les frames de la vidéo. Vous obtenez un seul asset de sortie avec le texte incrusté, et le pipeline reste court : construire le prompt, soumettre, interroger, livrer.

Que mettre dans le prompt

La typographie rendue par un modèle est moins prévisible que du texte composé, alors traitez le prompt comme une instruction étroite, pas comme l'endroit où décrire tout un système de design. Conseils pratiques :

• Gardez le texte court. Quelques mots par plan. Les phrases longues favorisent les dérives d'orthographe et l'encombrement de la mise en page.
• Citez les chaînes littérales entre guillemets. Si le texte doit apparaître exactement, mettez-le entre guillemets et exigez ce texte précis. Une description floue produit un résultat flou.
• Précisez la position et le style. « Grand texte blanc centré dans le tiers inférieur » est exécutable. « Un joli titre » ne l'est pas.
• Un élément textuel par plan. Demander un titre, un sous-titre et un filigrane dans le même segment multiplie les modes d'échec.
• Indiquez la langue. Si le texte n'est pas en anglais, précisez-le, car la couverture des glyphes varie.

À quoi s'attendre en retour

Traitez la sortie comme un brouillon, pas comme une spécification. Même un bon résultat peut présenter des glyphes déformés, un espacement irrégulier ou une occultation partielle par le mouvement. Vérifiez toujours les frames rendues avant de livrer ; un contrôle programmatique peu coûteux plus un coup d'œil humain aux premières et dernières frames contenant du texte attrapent la plupart des problèmes.

Quand cette voie l'emporte

Le texte natif est le bon choix par défaut lorsque le texte est accessoire et atmosphérique : enseignes dans une rue en arrière-plan, logo stylisé sur un produit, cartons de titre courts que vous acceptez de régénérer en cas d'erreur. Il l'emporte aussi lorsque vous ne pouvez vraiment pas vous offrir une seconde étape de rendu, par exemple dans un flux à délai serré où une requête par clip constitue le budget.

Le prix à payer est le contrôle. Tout changement de formulation, de style ou de synchronisation implique une nouvelle requête de génération, et les résultats ne sont pas déterministes d'un essai à l'autre. Concevez vos prompts et votre stockage pour que les clips régénérés remplacent proprement les anciens.

Voie deux : générer un asset propre et composer le texte soi-même

La voie des incrustations divise le travail en deux. D'abord vous générez un asset délibérément dépourvu de texte. Ensuite vous y composez les sous-titres et les incrustations, à l'aide d'un service de rendu ou de votre propre pipeline média.

Générer d'abord un asset propre

Demandez une composition sans texte : décrivez la scène, le sujet, le mouvement de caméra et la lumière, et évitez explicitement de demander du texte à l'écran. Si le modèle a tendance à inventer des enseignes ou du texte d'interface, mentionnez que l'image doit être exempte de texte lisible. La sortie est ici un asset de base — une entrée stable que vous pouvez réutiliser pour de nombreuses variantes de texte.

Composition a posteriori

L'étape d'incrustation consomme deux entrées : l'asset de base et une charge utile structurée de sous-titres/incrustations. Parce que vous contrôlez le moteur de rendu, vous obtenez des propriétés que le prompt ne peut pas garantir :

• Polices et tailles déterminées. La même charge utile se rend à l'identique à chaque fois, ce qui compte pour la cohérence de marque.
• Synchronisation précise. Les sous-titres peuvent s'aligner à la frame près sur la parole, un temps musical ou un changement de scène.
• Zones sûres et règles de mise en page. Vous pouvez imposer des marges, éviter les visages et les sujets clés, et maintenir le texte dans les zones sûres propres à chaque plateforme.
• Itérations peu coûteuses. Corriger une faute ou traduire un sous-titre, c'est re-rendre l'incrustation, pas régénérer la vidéo.
• Composabilité. Filigranes, tiers inférieurs et sous-titres se superposent indépendamment et s'activent selon la sortie.

Compromis

La voie des incrustations échange une dépendance au modèle contre une complexité de pipeline. Vous ajoutez une seconde requête, vous devez stocker quelque part les assets intermédiaires, et vous possédez la configuration de rendu. En contrepartie, le texte devient une donnée que vous pouvez versionner, tester et remplacer. Pour tout ce qui a de vrais besoins de sous-titrage — sous-titres d'accessibilité, variantes multilingues, formats sociaux modélisés — cet échange en vaut presque toujours la peine.

Un schéma pratique consiste à rendre les incrustations de manière non destructive : traitez l'asset de base et la charge utile de sous-titres comme source de vérité unique, et la vidéo composée comme un artefact dérivé que vous pouvez toujours régénérer.

Concevoir une charge utile de sous-titres qui survit aux deux voies

Si vous concevez bien vos données de sous-titres, le choix entre génération native et incrustations devient un détail de rendu plutôt qu'une réécriture. L'objectif est une charge utile unique qui peut à la fois être sérialisée en prompt pour le texte natif et fournie à un moteur de rendu pour les incrustations.

Champs essentiels

Modélisez chaque élément textuel comme un objet, en gardant contenu, synchronisation et présentation séparés :

{
  "track": "captions",
  "items": [
    {
      "text": "Tout ce que vous devez savoir",
      "start": 0.0,
      "end": 2.4,
      "style": { "role": "title", "align": "center", "position": "lower_third" },
      "lang": "fr"
    }
  ]
}

Décisions de conception clés :

• Le temps en secondes, en flottants. Une base temporelle unique pour tout le projet, convertie en frames uniquement au rendu.
• Styliser par rôle plutôt que par valeurs absolues. Nommez des rôles comme title, caption et lower_third, et résolvez-les en polices et tailles dans le moteur de rendu. Cela rend la charge utile portable entre formats.
• Noms de pistes. Séparez les pistes captions, titles et watermark afin de pouvoir activer ou désactiver une piste selon la sortie.
• Étiquette de langue par élément. Nécessaire au choix de police et aux passages de traduction ultérieurs.
• Aucune information de présentation intégrée dans le champ texte. Ne mettez jamais d'indication de style dans le texte ; c'est le rôle de l'objet style.

Alimenter deux voies à partir d'un seul schéma

Pour la génération native, écrivez un petit adaptateur qui sélectionne les éléments les plus importants et les convertit en instructions de prompt : le texte littéral, sa position et un descripteur de style. Rendez cet adaptateur volontairement avec perte — le rendu natif ne saurait de toute façon pas suivre une piste de sous-titres complète.

Pour les incrustations, transmettez la charge utile au moteur de rendu, qui résout les rôles et les positions et le dessine dans la fenêtre temporelle de chaque élément.

Le bénéfice : votre code applicatif construit un objet de sous-titres, et passer du natif aux incrustations (ou revenir au natif pour un clip précis) est un changement de configuration, pas une migration de données.

Une requête d'incrustation fonctionnelle, étape par étape

Voici la séquence de la voie des incrustations, exprimée sous forme d'étapes API. Les noms d'endpoints et les paramètres exacts dépendent du fournisseur, mais la forme est stable, et une fine couche d'abstraction la maintient stable entre backends.

Étape 1 : soumettre la génération de l'asset propre

POST /video/generations
{
  "prompt": "Un lent travelling avant dans un bureau moderne, aucun texte à l'écran, lumière naturelle",
  "duration_seconds": 6,
  "aspect_ratio": "16:9"
}

Gardez le prompt sans texte et stockez l'identifiant de tâche renvoyé.

Étape 2 : interroger jusqu'à ce que l'asset soit prêt

GET /video/generations/{job_id}

Interrogez avec un backoff plutôt qu'en boucle serrée. Traitez des états comme queued, running, succeeded et failed comme des états de première classe dans votre code, et persistez l'URL ou l'ID de l'asset résultant afin qu'un plantage ne perde pas la génération.

Étape 3 : soumettre le rendu de l'incrustation

POST /video/overlays
{
  "source_asset": "asset_abc123",
  "captions": {
    "track": "captions",
    "items": [
      { "text": "Livraison aujourd'hui", "start": 0.4, "end": 2.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "fr" },
      { "text": "Aucune reconstruction nécessaire", "start": 2.2, "end": 4.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "fr" }
    ]
  }
}

Notez que la requête d'incrustation ne porte que l'asset source et les données textuelles. Elle ne régénère pas l'asset, et c'est précisément pourquoi les itérations sont peu coûteuses.

Étape 4 : récupérer le résultat composé

Interrogez la tâche d'incrustation de la même manière que la tâche de génération, puis récupérez l'asset final. Stockez l'asset de base, la charge utile de sous-titres et la sortie ensemble, pour que la composition soit reproductible.

En code, encapsulez les étapes 1 à 4 dans une fonction qui prend un prompt et une charge utile de sous-titres et renvoie l'asset final. Cette fonction est votre véritable interface ; les différents endpoints sont des détails d'implémentation interchangeables.

Vérifications de fiabilité avant publication

Les pipelines de texte sur vidéo échouent discrètement : sous-titres rognés, lignes mal traduites, régénérations jamais nettoyées. Ajoutez des contrôles avant que les utilisateurs ne les voient.

Vérifier le texte rendu

• Voie native : échantillonnez des frames au début et à la fin de chaque fenêtre de texte et inspectez-les. Automatisez les contrôles de lisibilité de base autant que possible, mais gardez une étape de revue humaine pour le texte destiné aux clients, car la typographie des modèles peut se dégrader de manière imprévisible.
• Voie des incrustations : validez la charge utile avant le rendu — pas de chevauchement temporel entre éléments, plage dans la durée du clip, langues et rôles pris en charge. Après le rendu, échantillonnez des frames aux frontières des éléments pour confirmer que rien n'est rogné.

Rendre les tentatives sûres

• Clés d'idempotence sur les requêtes de soumission, pour qu'un appel réseau réessayé ne crée pas de tâche de génération en double.
• Machine à états par tâche : queued → running → succeeded/failed, persistée, pour qu'un redémarrage reprenne au lieu de repartir de zéro.
• Interrogation bornée, avec backoff et délai d'expiration, présentant un échec clair plutôt qu'une boucle infinie.
• Stockez les assets intermédiaires. Si l'étape d'incrustation échoue, vous ne devriez pas payer pour régénérer un asset que vous possédez déjà.

Maîtriser le coût sur toute la chaîne

La voie des incrustations comporte deux étapes facturées — génération et rendu — alors surveillez les deux. Suivez la fréquence à laquelle vous régénérez des assets par rapport à un simple re-rendu d'incrustations ; si la régénération d'assets domine, votre découpage natif/incrustations est probablement inadapté à cette charge de travail. Mettez en cache l'asset final par couple (asset de base, charge utile de sous-titres), afin que les requêtes répétées pour la même sortie soient gratuites.

Observabilité

Journalisez ensemble le prompt, le hachage de la charge utile de sous-titres, l'ID de tâche et l'ID de l'asset final. Quand un utilisateur signale une erreur de sous-titre, vous voulez pouvoir déterminer en quelques secondes si le problème vient de la génération, des données ou du rendu. Traitez la charge utile de sous-titres comme une source de vérité versionnée, pour que vous puissiez toujours expliquer ce que le moteur de rendu a été chargé de dessiner.

Choisir votre workflow par défaut

Prenez ceci comme règle de départ, et réexaminez-la à mesure que le produit grandit.

Choisissez le texte natif lorsque le texte est décoratif ou accessoire, la formulation est courte, vous acceptez la régénération comme moyen de corriger les erreurs, et ajouter une seconde étape de rendu ne vaut pas le temps d'ingénierie pour ce clip.

Choisissez la voie des incrustations lorsque le texte doit être exact, synchronisé, traduit, restylé ou réutilisé sur plusieurs sorties. Sous-titres, titres secondaires, tiers inférieurs et formats marketing modélisés tombent presque toujours ici. La requête supplémentaire est le prix du déterminisme.

Un mix est raisonnable. Beaucoup d'équipes génèrent par défaut des assets propres, s'appuient sur les incrustations pour tout ce qui compte, et réservent le texte natif aux plans d'ambiance jetables. Comme les deux voies consomment la même charge utile de sous-titres, vous pouvez prendre cette décision clip par clip sans traitement spécial de vos données.

Quelle que soit votre choix, gardez l'intégration derrière une fine abstraction : une fonction qui prend un prompt et une charge utile de sous-titres et renvoie l'asset final. Cette frontière est précisément ce qui vous permet de changer de backend de génération, d'ajouter des options de rendu, ou de déplacer un clip individuel entre workflows sans toucher à la logique de sous-titres que vous avez eu tant de mal à bien calibrer.