API Pro : générer des vidéos avec du son

Un clip à partir d'un prompt, ou l'animation d'une image fixe que tu fournis. Le fichier est un MP4, avec du son quand tu le demandes.

Soumettre une vidéo

POST /videos

{ "prompt": "a woman in a white linen dress walks along a beach at sunset, wind in her hair, she turns and smiles at the camera",
  "width": 1080, "height": 1920, "audio": true }

Cadence par défaut : 30 i/s. Les clips étaient rendus à 24 i/s. Sans fps, un clip de même length est donc plus court qu'avant (241 images : 8 s au lieu de 10 s). Envoie "fps": 24 pour garder l'ancien comportement.

La réponse :

{ "jobId": "...", "seed": 908172, "cost": 30 }

Le coût est calculé et annoncé à la soumission, avant qu'aucun crédit ne soit débité. La graine (seed) est renvoyée aussi, qu'elle ait été donnée ou tirée au hasard.

Formats et tarif

Une vidéo est facturée par format, à un tarif fixe indépendant de sa durée. Base : 5 crédits.

Le tarif fixe est multiplié par 2 en 720p et par 3 en 1080p, puis le son double le prix. Les facteurs s'appliquent au tarif de base, pas l'un à l'autre : 1080p avec son coûte 5 x 3 x 2 = 30 crédits. Jusqu'à 481 images, soit 20 s à 24 i/s, la durée ne change rien (5 s ou 20 s, même tarif). Au-delà de 481 images (jusqu'à 721, en consistency enhanced seulement, durée fixe), le prix du format est doublé. La cadence (fps) ne change pas le prix, mais les paliers se comptent en images : à 30 i/s, le prix normal va jusqu'à 16 s ; à 60, jusqu'à 8 s (12 s au double en enhanced).

Une exception : en Qualité, le 480p sans son coûte 2 crédits, quelle que soit sa durée (depuis le 11 octobre 2026). Le Multi-Ref et la cohérence renforcée gardent le forfait du format, 5 crédits.

La taille que tu récupères. Le moteur travaille en multiples de 32 et en deux étapes, donc le fichier ressort à 768 x 1280 (ou 1280 x 768) en 720p et 1088 x 1920 (ou 1920 x 1088) en 1080p. Le 480p reste à 480 x 832 (ou 832 x 480), sauf en cohérence renforcée. Utile à savoir si tu assembles ou superposes nos rendus.

La voie turbo est retirée depuis le 11 octobre 2026 : une demande turbo est rendue en Qualité 480p et se paie comme elle (2 crédits sans son, 10 avec son).

Connaître le prix avant de soumettre

POST /videos/quote prend le même corps que POST /videos et effectue le même calcul, mais rien n'est créé : pas de rendu, pas de crédit retenu, pas de quota consommé. Appelle-le avant de valider, surtout depuis un agent travaillant avec un budget limité.

{ "cost": 30, "mode": "ltx25", "format": "1080p", "audio": true, "fps": 30, "duration_auto": true,
  "seconds_max": 16, "detail": "flat 5 x 3 (1080p) x 2 (sound) = 30" }

detail détaille le calcul ; fps est la cadence retenue, et seconds_max la durée en secondes à cette cadence. Avec "consistency": "enhanced", le devis accepte une durée fixe jusqu'à 721 images et applique le palier au-delà de 481 images (x 2 (over 20 s) dans detail à 24 i/s, x 2 (over 481 frames) à une autre cadence). La même route existe pour les images, POST /images/quote, qui répond toujours { "cost": 1, ... } : une image coûte toujours 1 crédit.

Pour un clip Ultra facturé à la seconde, le devis donne la durée facturée dans seconds, et detail détaille le prix à la seconde.

Interroger, télécharger, annuler

Les mêmes routes que pour les images, sous /videos.

• GET /videos/{jobId} : pending / completed / failed, mêmes champs. Une prolongation renforcée peut finir en failed avec "error": "extension_not_applied" (le moteur n'a pas repris la fin du clip précédent) : rien n'est débité, relance-la.
• GET /videos/{jobId}/file : le MP4 (Content-Type: video/mp4).
• POST /videos/{jobId}/cancel : annule, et rien n'est débité.

En Ultra facturé à la seconde, un rendu déjà en calcul ne s'arrête plus : l'annulation répond 409 render_in_progress, et le clip est livré et facturé. Un clip que le moteur refuse à la sortie finit en failed, avec une phrase dans detail et le code du moteur dans reason : rien n'est débité.

Une vidéo prend 1 à 5 minutes, plus longtemps quand le moteur démarre à froid. Interroge toutes les 3 secondes et télécharge dès que le statut est completed : le fichier n'est pas archivé.

Plusieurs plans dans un clip

Un seul prompt peut contenir plusieurs plans séparés par des coupes franches, jusqu'à 20 secondes au total à 24 i/s (16 s à 30, la cadence par défaut). Décris-les dans l'ordre : Shot 1: <cadrage>, <action>. Cut to Shot 2: .... Répète dans chaque plan ce qui doit rester identique (personnage, tenue, lieu, lumière), et termine par une phrase d'ambiance commune.

Pas de timecodes : laisse duration_auto actif, le moteur choisit la durée (jusqu'à 20 s à 24 i/s, 16 s à 30) et l'endroit des coupes. Deux à quatre plans par clip donnent les meilleurs résultats.

A cinematic sequence of three shots, same woman, same place, same lighting throughout.
Shot 1: Wide shot, night, light rain on a narrow Paris street with glowing café windows. A woman in a long beige trench coat walks toward the camera under a transparent umbrella, wet cobblestones reflecting warm yellow streetlights.
Cut to Shot 2: Close-up on her face under the umbrella, raindrops on the plastic, warm café light on her cheek, she smiles softly.
Cut to Shot 3: Medium shot from inside the café through the rainy window, she pushes the door open and steps in, warm light spilling onto the wet pavement.
Calm, melancholic, romantic mood.

Plusieurs plans dans un clip, ou une séquence ? Les deux ne font pas la même chose :

Prolonger un clip

Un clip peut être prolongé : le plan suivant continue le mouvement du précédent, sans arrêt au raccord. Il s'appuie sur environ la dernière seconde du clip précédent, pas sur une seule image fixe. Ajoute à POST /videos :

Le plan prolongé reprend la résolution du clip précédent : width et height sont ignorés avec extend_job_id, et avec extend_video la taille est lue depuis le fichier que tu envoies. Il contient uniquement les nouvelles images, de sorte que les plans mis bout à bout forment une seule vidéo continue. Il garde la cadence du clip précédent : omets fps (il la reprend) ou donne la même ; une autre est refusée (extend_fps_mismatch). length est la nouvelle durée du plan (121 = 5 s de plus à 24 i/s), et elle est exacte : la durée automatique ne s'applique pas à une prolongation. Une prolongation coûte le prix d'un clip.

Limites : pas d'image de fin ni d'images clés en même temps, sauf en cohérence renforcée.

Le son continue au raccord. Avec audio: true, quand la fin du clip précédent porte une piste son, le nouveau plan reprend ce son au lieu d'en inventer un autre. Avec extend_job_id, la fin coupée garde le son du clip ; avec extend_video, envoie la fin avec son son. Sans piste son dans cette fin, en cohérence renforcée et en Ultra, le son repart de zéro avec le plan : conserve la même ambiance dans chaque prompt, pour que le raccord s'entende le moins possible.

Prolonge un clip peu après sa fin. Plus tard il n'est plus disponible de notre côté (clip_unavailable), et tu envoies sa fin toi-même dans extend_video.

Prolonger un plan Ultra, vers l'avant ou vers l'arrière

Un plan rendu en Ultra à la seconde se prolonge lui aussi en Ultra, vers l'avant ou vers l'arrière ; tout autre clip se prolonge comme ci-dessus. Envoie POST /videos avec "quality": "max" et :

• Le rendu ne contient que la partie nouvelle, de la durée d'un clip Ultra (length / fps, 5 s en durée automatique). Il prend la résolution du plan (width et height sont ignorés) et se raccorde à sa dernière image (forward) ou à sa première (backward).
• Pas d'image de départ, de références (multiref), de mouvement ni de cohérence renforcée. backward ne va pas dans une séquence, qui range ses plans à la suite.
• Prix : la partie nouvelle au prix de l'Ultra à la seconde, plus, par seconde du plan prolongé, 2 crédits en 480p, 5 en 720p et 13 en 1080p (ultra.extend_per_second dans GET /pricing). Ces secondes s'arrondissent à la seconde supérieure (à 0,1 s près) et se comptent à 24 images par seconde : un plan à cadence plus haute compte au prorata (2 s à 60 i/s comptent 5 s). POST /videos/quote avec les mêmes champs donne extend_seconds et le prix exact.
• Plan de plus de 24 heures : dépose son fichier original, tel que livré par GET /videos/{jobId}/file. POST /extensions avec { "size": <octets> } rend upload_id, upload_url, headers et expires_in (900 s) ; envoie le fichier par PUT upload_url avec exactement ces headers, puis passe extend_upload_id dans les 2 heures. Un dépôt sert à un rendu : un MP4 de 4 à 30 s, 60 Mo et 1080p au plus. Avant le rendu, chaque vidéo envoyée au mode Ultra (un mouvement ou une vidéo à prolonger) est vérifiée, et rien n'est débité si elle est refusée (400 input_video_out_of_limits) : 24 à 60 images par seconde, un rapport largeur/hauteur de 0,4 à 2,5 et, pour un rendu, 30 s et 10 fichiers au plus pour les vidéos et les sons de référence réunis. Pour un visage réaliste, un fichier réencodé ou remonté est refusé (400 engine_refused) : seul l'original passe. Une vidéo que le mode Ultra n'a pas rendue (le rendu d'un autre mode, par exemple) ne se prolonge pas en Ultra quand elle montre un visage réaliste (400 extension_real_face, rien n'est débité) : prolonge-la en mode Qualité, ou refais le plan en Ultra.

Cohérence renforcée

Avec "consistency": "enhanced", le clip est rendu par une voie qui tient mieux le mouvement, les visages et le décor sur la durée. Elle va jusqu'à 721 images par plan, soit 30 s à 24 i/s et 24 s à 30 (length, durée fixe) et sert surtout aux vidéos longues :

• Premier plan : un clip normal (prompt, image de départ, keyframes, end_image), jusqu'à 721 images.
• Prolongation : extend_job_id (ou extend_video) comme dans Prolonger un clip, avec la même consistency. length reste la durée nouvelle (jusqu'à 721, soit 30 s de plus à 24 i/s). Une prolongation renforcée accepte aussi des keyframes, dont at compte depuis la première image nouvelle, et une image de fin end_image, posée sur la dernière image du plan : par exemple l'image de départ du premier plan, pour qu'une vidéo longue boucle.

Mode Qualité seulement (mode ltx25, sans quality: "max"), jusqu'au 1080p, pas en Multi-Ref (400 consistency_mode). Prix : le forfait du format (480p sans son : 5 crédits) jusqu'à 481 images nouvelles (20 s à 24 i/s), doublé au-delà (voir la grille plus haut). Cadences : 24, 30, 50 ou 60. Au-delà de 30, la durée est fixe (fps_requires_fixed_duration sinon) ; 50 donne un léger ralenti (voir fps). Le rendu prend plus de temps qu'un clip standard, et son démarrage peut attendre une carte graphique plus grosse (plans longs). Une séquence garde la même consistency pour tous ses plans. Taille livrée : la même qu'en Qualité au 720p et au 1080p ; au 480p, le petit côté sort à 448 (448 x 832, 832 x 448, 448 x 448), cette voie travaillant par multiples de 64.

Certains prompts ne sont pas encore pris en charge. Pour eux, un plan seul de 20 s au plus (15 s avec une end_image, en durée fixe) est rendu en cohérence standard, au même prix. Au-delà (length au-dessus de 481 avec duration_auto: false, ou de 361 avec une end_image), en prolongation ou dans une séquence, la demande est refusée avec 400 consistency_explicit : raccourcir le plan ou demander consistency: "standard".

Longue vidéo (séquences)

Un clip dure 481 images au maximum, soit 20 s à 24 i/s (721 en cohérence renforcée, 30 s à 24 i/s). Pour aller plus loin, une séquence enregistre chaque plan au fur et à mesure de son rendu, puis les assemble en un seul MP4 sans ré-encodage. Une minute, par exemple, c'est 3 plans de 20 s, ou 2 plans de 30 s en cohérence renforcée, à 24 i/s.

1. POST /sequences ouvre une séquence et répond { "sequence_id": "seq_...", ... }.
2. POST /videos avec "sequence_id": "seq_..." pour chaque plan : le premier comme d'habitude, les suivants avec extend_job_id pointant vers le plan précédent. Chaque plan est enregistré dans la séquence, dans l'ordre de soumission, dès que GET /videos/{jobId} le voit terminé.
3. POST /sequences/{id}/export une fois le dernier plan terminé. Il répond avec seconds, resolution et file_url.
4. GET /sequences/{id}/file : la vidéo assemblée (MP4).

Autres routes : GET /sequences/{id} donne l'état (plans enregistrés ou encore attendus), POST /sequences/{id}/clips avec { "job_id": "..." } enregistre un rendu manuellement, et DELETE /sequences/{id} supprime la séquence immédiatement.

Règles. Chaque plan a la même résolution (les prolongations la reprennent) et le même choix de son, tous avec son ou tous sans, la même consistency et la même cadence (fps) : le premier plan les fixe, et un plan qui diffère est refusé (409 consistency_mismatch, 409 sequence_fps_mismatch ; 422 encoding_mismatch pour un plan rangé à la main). Un plan sans fps prend celle de la séquence. Au maximum 30 plans par séquence et 5 séquences en cours par licence.

Ce que nous conservons, et combien de temps. Les plans d'une séquence en cours sont effacés 30 minutes après l'ajout du dernier, et la vidéo assemblée 24 heures après l'export. Ensuite, tout est supprimé.

Exporter le dossier du projet

Un dossier de projet réunit dans un ZIP tout ce qu'il faut pour reprendre une vidéo ailleurs ou l'automatiser : les plans, leurs références, le montage, et un manifeste qui permet de rendre chaque plan de nouveau. Il est gratuit : aucun rendu.

• POST /videos/{jobId}/export : un rendu de POST /videos (plan seul, Multi-Ref, prolongation).
• POST /sequences/{id}/project : tous les plans d'une séquence, bout à bout.
• Corps facultatif, les mêmes choix que la fenêtre d'export de l'application :
  • include_media (true par défaut) : les vidéos des plans et leurs originaux signés. false : aucune vidéo (ni clip, ni original, ni film) ; les plans gardent leur texte, leurs réglages et leurs références ("state": "expired") et le manifeste porte videos_included: false.
  • include_references (true par défaut) : les vues des personnages et les images des éléments, dans references/. false : aucune n'est copiée ; leurs noms, @mentions, id et empreintes restent au manifeste (references_included: false).
  • exclude_references : les références à ne pas copier, une par une, par id (character_id, subject_id), nom ou @mention, par exemple ["@Parc", "chr_..."] (200 au plus). Le manifeste porte references_included: "partial" et "included": false sur chaque exclue (false si toutes le sont). Une entrée qui ne désigne aucune référence de l'export : 400 unknown_reference.
  • include_film (séquence seulement, false par défaut) : le film d'une séquence déjà assemblée ; il demande include_media (sinon 400 invalid_export_options, comme une option qui n'est pas un booléen ou un exclude_references qui n'est pas une liste de textes).
  • manifest_only: true : le manifeste seul, sans ZIP.

La réponse est { "manifest": { ... }, "file_url": "...", "export_id": "exp_...", "expires_at": "...", "bytes": n }, et GET /exports/{id}/file télécharge le ZIP. Un export à la fois par licence (409 export_in_progress), 2 Go au plus (413 export_too_large : exporte les plans un par un).

Ce que nous conservons, et combien de temps. À chaque POST /videos accepté, le serveur garde une fiche du rendu sans aucune image ni vidéo : le texte, les réglages, les identifiants (une image envoyée en base64 n'y laisse que son empreinte). Elle est effacée 24 heures après la soumission ; au-delà, l'export répond 404 unknown_export. Le ZIP est effacé 45 minutes après son premier téléchargement, 2 heures après sa création au plus. Un plan que le serveur n'a plus sort en "state": "expired", sans son fichier mais avec son texte, ses réglages et ses références : un agent peut le rendre de nouveau avec api_request.

Séquence. L'assemblage efface les plans un par un. Pour avoir les plans et le film, exporte le projet avant d'assembler, puis assemble et exporte de nouveau avec { "include_film": true } : le film s'ajoute, et les plans sortent alors en expired.

Mode Ultra

Le mode Ultra est le rendu vidéo le plus fin. Ajoute "quality": "max" à POST /videos (avec mode ltx25, la valeur par défaut). Il se facture à la seconde, ou à prix fixe avec un LoRA ou en prolongation d'un clip qui n'a pas été rendu à la seconde ; prolonger un plan Ultra, vers l'avant ou vers l'arrière, se facture à la seconde. POST /videos/quote donne le prix exact de ta demande.

À la seconde

Le clip est facturé à la seconde selon sa résolution, son compris :

• Durée : de 4 à 30 s, à 24 images par seconde, connue avant le rendu : 5 s en durée automatique (duration_auto, par défaut), sinon length / fps (24 si fps est absent), arrondie à la seconde.
• Format : celui demandé, au rapport le plus proche ; le 480p est rendu en 480p. Au-delà du 1080p : resolution_outside_ultra.
• Image de départ (image) : possible. Le moteur peut refuser un texte ou une image à l'envoi : 400 engine_refused, avec sa raison dans detail et son code dans code ; rien n'est débité.
• Pas de graine : seed est ignorée et la réponse n'en donne pas.
• Annulation : libre tant que le rendu attend son tour. Une fois en calcul, 409 render_in_progress, et le clip est livré et facturé.
• Pas d'image d'arrivée, d'images clés ni de cohérence renforcée en Ultra.

À prix fixe

Avec un LoRA ou en prolongation d'un clip qui n'a pas été rendu à la seconde, l'Ultra est rendu avec le modèle vidéo complet, à prix fixe :

Le prix est fixe par format : son et durée n'y changent rien. L'Ultra commence au 720p : une demande en 480p est rendue, et facturée, en 720p. POST /videos/quote donne le prix exact. Le 1080p (1920 x 1088) est le plafond, dans tous les modes : la 4K n'est plus proposée. Une taille plus grande est refusée (ultra_4k_unavailable avec quality: "max", resolution_above_quality sans).

• Durée : 481 images au plus, comme un clip (20 s à 24 i/s, 16 s à 30, 8 s à 60). La prolongation et la vidéo longue marchent aussi en Ultra. Une prolongation garde la taille du clip qu'elle continue, et sous le 720p elle est facturée au prix du 720p.
• Temps : plusieurs minutes pour un clip de 5 s, davantage pour un clip de 20 s. Le démarrage peut attendre qu'une grosse carte graphique se libère.
• Pas de transition (end_image) en Ultra (ultra_incompatible).
• Pas d'images clés (keyframes) en Ultra (keyframes_mode).
• Un LoRA de personnage de ton compte s'applique en Ultra comme en mode normal.

Multi-Ref Vidéo

Un clip où jouent 1 à 4 personnages (jusqu'à 12 en Ultra), chacun reconnaissable, dans un décor facultatif, avec au besoin des objets, des animaux et un lieu enregistrés. Les personnages viennent de GET /characters : fabriqués à partir d'une photo par l'API, ou dans l'appli. Les objets, animaux et lieux viennent de GET /subjects. Ajoute l'objet multiref à POST /videos (droit videos) et désigne chaque personnage par @Nom dans le prompt :

{
  "prompt": "@Lea walks toward @Tom in a sunny kitchen and hands him a cup. Sound: footsteps, soft music.",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Lea", "description": "a 28 year old woman with long red hair" },
      { "character_id": "chr_21bc...", "name": "Tom", "description": "a 30 year old man", "strength": 1.2 }
    ],
    "background_b64": "<facultatif : image du décor>",
    "background_description": "a sunny kitchen"
  },
  "width": 1088, "height": 1920,
  "audio": true
}

• Prompt en anglais, un paragraphe au présent ; Sound: pour le son, répliques entre guillemets, exactly 2 people et la place de chacun si utile, pas de négations. Une créature se décrit par sa nature. Un @Nom qui ne désigne aucun personnage est refusé (unknown_mention).
• Formats (width x height) : portrait 480 x 832, 720 x 1280, 1088 x 1920 ; paysage 832 x 480, 1280 x 720, 1920 x 1088 ; carré 480 x 480, 720 x 720, 1088 x 1088. Pas de 4K ; le 480p en Qualité seulement.
• Modes : Qualité (par défaut), ou Ultra (quality: "max"). Pas de prolongation ni de transition.
• Durée : automatique (duration_auto, par défaut), ou fixe avec duration_auto: false et length 121 (5 s), 241 (10 s) ou 481 (20 s) à 24 i/s ; à une autre cadence, les mêmes durées comptées en images, 481 au plus (à 30 : 145, 297, 481 ; à 60 : 297, 481).
• Cadence : fps 24, 30 (par défaut) ou 60, comme un clip ; length se compte à cette cadence, 481 images au plus (16 s à 30, 8 s à 60).
• Prix : celui d'un clip. En Qualité, le forfait du format dans la grille plus haut, doublé avec le son ; le 480p sans son reste à 5 crédits (le prix bas de la Qualité ne s'applique pas au Multi-Ref). POST /videos/quote avec "multiref": true donne le prix exact.
• Le serveur met les vues au format exact de la vidéo : envoie les personnages tels quels. Un personnage qui n'a qu'une vue est rendu, avec warnings limited_likeness dans la réponse : la ressemblance est limitée.
• Voix des fiches : avec du son, characters[0] et characters[1] parlent avec la voix de leur fiche par défaut, quand elle est en ligne (has_voice) ; voice generated laisse le modèle en faire une. La réponse donne la voix de chacun dans voices (character_id, voice : character, custom ou generated).
• Voix des personnages (voice_b64) : le modèle fait parler le personnage avec cette voix, lèvres comprises ; le serveur en prend les 5 premières secondes. Deux voix au plus, sur characters[0] et characters[1] (le moteur supporte 2 voix). Range characters dans l'ordre du dialogue : characters[0] parle en premier, characters[1] lui répond. Il faut du son ("audio": true), sinon voice_requires_audio ; une voix sur un autre personnage : voice_slot ; un fichier illisible : unsupported_audio_format ; plus de 4 Mo : audio_too_large. Seules les 5 premières secondes servent : envoie un extrait court. Le corps entier de la requête ne dépasse pas 30 Mo (au-delà, un 413 sans corps JSON). Sans supplément de prix.
• Le suivi, le téléchargement et l'annulation sont ceux d'une vidéo (voir plus haut).

Objets, animaux et lieux enregistrés. Deux champs de plus de multiref font jouer les sujets que tu as enregistrés à partir de tes images :

name vaut par défaut le premier mot du nom du sujet, et chaque @Nom du prompt se reconnaît comme celui d'un personnage. Un lieu passé dans subjects, ou un objet passé en location, est refusé (invalid_subject_type). Le prix ne change pas : c'est celui d'un clip. Un sujet joue avec ses 5 premières images (toutes en Ultra, 6 au plus).

"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "subjects": [{ "subject_id": "sub_1c2d...", "name": "Rex" }],
  "location": { "subject_id": "sub_9e8f...", "name": "Loft" }
},
"prompt": "@Lea throws a ball to @Rex across @Loft. Sound: barking, laughter."

En Ultra, un clip Multi-Ref suit les règles de l'Ultra facturé à la seconde : même prix à la seconde, son compris, de 4 à 30 s à 24 images par seconde (5 s en durée automatique), du 480p au 1080p, sans graine.

• Chaque personnage part avec sa character sheet (ou, s'il n'en a pas, avec toutes ses images), le tout assemblé par le serveur en une seule image. Chaque objet, animal ou lieu part avec toutes ses images (6 au plus).
• Le premier rendu d'un personnage prépare cette image, ce qui prend quelques dizaines de secondes de plus. Son jobId commence alors par sdp- et se suit comme les autres.
• Pas de voix : voice_b64 et la voix de la fiche sont ignorées (warnings voice_ignored), et strength n'a pas d'effet.
• Le moteur peut refuser une image de référence, un visage réel par exemple. Le rendu finit alors en failed avec la raison, et rien n'est débité.

Styles, tenues et mouvement. En Ultra seulement (quality: "max"), trois champs de plus dans multiref ; ailleurs, la requête est refusée (multiref_ultra_only), jamais rendue sans eux.

• 30 images au plus en Ultra, personnages, sujets, styles, tenues et lieu confondus (multiref_too_many_images), dont 12 personnages au plus (multiref_characters_required au-delà). 8 sont conseillés : de 9 à 12, le rendu part avec warnings many_characters, car certains peuvent manquer ou se mélanger. Un style hors de styles, ou une tenue hors de outfits, est refusé (invalid_subject_type).
• Prix du mouvement : 3 crédits par seconde de la vidéo de mouvement (arrondie à la seconde supérieure), en plus du rendu, lus dans GET /pricing (ultra.motion_per_second) ; POST /videos/quote avec le même multiref.motion donne motion_seconds et le prix exact.
• Dépôt direct, pour une vidéo de mouvement lourde : POST /motions avec { "size": <octets> } (20 Mo au plus) rend motion_id, upload_url, headers et expires_in (900 s) ; envoie le fichier par PUT upload_url avec exactement ces headers, puis passe multiref.motion.motion_id à POST /videos dans les 2 heures. Un motion_id sert à un rendu.

"quality": "max",
"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "styles": [{ "subject_id": "sub_a1b2..." }],
  "outfits": [{ "subject_id": "sub_c3d4...", "name": "RedGown", "worn_by": "Lea" }],
  "motion": { "motion_id": "4f0c2a9b1d7e6a35", "description": "a low tracking shot from the side" }
},
"prompt": "@Lea walks along a seaside promenade at sunset."

Les codes d'erreur des styles, des tenues et du mouvement sont dans Limites et erreurs.

Avec le serveur MCP, l'agent fait tout cela avec tendre_multiref_video : demande la scène et nomme les personnages, les objets, les animaux et le lieu (subjects, location_id).

Face swap

La personne filmée dans ta propre vidéo devient un de tes personnages : visage, cheveux, corps et tenue (ou la tête seule, voir part), en gardant ses gestes, ses lèvres et le décor, et sa voix sauf si le personnage a la sienne (voir voice). C'est le Face swap de l'appli (le remplacement de personnage), sur un passage de 20 s au plus : un seul personnage, sans enchaînement ni transition. La requête : POST /faceswap (droit videos) :

{
  "video_b64": "<la vidéo en base64 : MP4, MOV, WebM ou MKV, 20 Mo au plus>",
  "character_id": "chr_8f3a...",
  "start": 2,
  "duration": 6,
  "scene": "@Lea wears a long red coat.",
  "zone": "normal",
  "likeness": 1
}

Vidéo et voix ensemble : 22 Mo au plus, pour que le corps de la requête reste sous 30 Mo (au-delà, un 413 sans corps JSON).

• Le serveur prépare tout. Il coupe le passage, le met à la cadence de travail (30 i/s pour une source à 29 i/s ou plus, 50 et 60 compris, 24 en dessous) et au format de travail (multiples de 128, petit côté de 768, le rapport le plus proche de ta vidéo), et met les vues du personnage à ce format.
• Ce que tu récupères : la vidéo du passage au format de travail, environ 1 million de pixels (768 x 1408 pour une vidéo verticale, par exemple), aux proportions de ta vidéo à 5 % près. La pleine résolution et l'enchaînement de plusieurs personnages restent propres à l'appli tendre.AI sur ordinateur : elle recolle le personnage sur la vidéo d'origine, dans sa pleine résolution, et enchaîne plusieurs personnages.
• Prix : 6 crédits par seconde du passage préparé (seconds dans la réponse), arrondi au crédit supérieur. La réponse donne jobId, seed, cost et le passage préparé (width, height, length, fps, seconds, audio, voice, views, part). Un personnage qui n'a qu'une vue est rendu, avec warnings limited_likeness.
• Pas de devis : ni POST /videos/quote ni le tendre_quote du MCP ne connaissent le Face swap. Pour calculer le prix avant de soumettre, lis grid.body_swap dans GET /pricing : secondes du passage x per_block_720p (le prix d'un bloc) / block_seconds (la durée d'un bloc), arrondi au crédit supérieur.
• Certaines scènes sont rendues à partir des trois portraits du personnage recadrés à la tête (heads_only dans la réponse), et la tenue de ses vues n'est plus imposée : c'est la scène qui décide.
• Un Face swap compte comme un usage du personnage et repousse son effacement, comme le Multi-Ref.
• Le suivi, le téléchargement et l'annulation sont ceux d'une vidéo (voir plus haut) : GET /videos/{jobId}, GET /videos/{jobId}/file, POST /videos/{jobId}/cancel.
• Erreurs propres : video_required, video_too_large, unreadable_video, invalid_start, passage_too_short, invalid_duration, invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part, invalid_voice_choice, character_required, unknown_character, audio_too_large (une voix de plus de 2 Mo), face_swap_too_large (le passage reste trop lourd une fois préparé : raccourcis duration), server_busy (deux vidéos déjà en préparation : réessaie après Retry-After, 20 s), face_swap_unavailable et face_swap_price_missing (Face swap fermé, ou sans prix : réessaie plus tard). Le sens de chacune : Limites et erreurs.
• Ta vidéo transite par nos serveurs le temps d'être préparée, puis part vers la carte graphique qui fait le rendu, comme toute image source.

N'utilise que des vidéos de personnes qui ont donné leur accord : c'est une règle des conditions d'utilisation.

Avec le serveur MCP, l'agent fait tout cela avec tendre_face_swap.