Clipwright

API Clipwright

Une API HTTP qui transforme un script en vidéo UGC avec synchronisation labiale, ou un script ou un bref descriptif en vidéo sans visage : narration sur un clip d’ouverture animé et des scènes illustrées. Elle est conçue pour être pilotée par un agent : chaque appel est une seule requête JSON, chaque refus indique la marche à suivre, et rien n’est publié nulle part. Chaque mot de cette page figure également dans un fichier Markdown à https://clipwright.io/docs.md et dans un bref contrat destiné aux agents à https://clipwright.io/llms.txt qui lisent du texte. Le fichier OpenAPI 3.1 à https://api.clipwright.io/openapi.json est le contrat REST lisible par machine, généré à partir des schémas que l’API valide.

Authentification

Chaque appel est envoyé à https://api.clipwright.io et transmet la clé dans un en-tête :

Authorization: Bearer cw_your_key_here

• Les clés commencent par cw_ et ne sont affichées qu’une seule fois, lors de leur émission. Nous ne conservons qu’une empreinte ; une clé perdue est donc remplacée, jamais récupérée.
• Émettez et révoquez des clés à https://app.clipwright.io/api-keys dans le tableau de bord. La révocation prend effet dès la requête suivante.
• @clipwright/cli et @clipwright/mcp-server lisent la clé depuis la variable d’environnement CLIPWRIGHT_API_KEY ; @clipwright/sdk la prend en argument.
• Un appel sans clé, ou avec une clé révoquée, est refusé avec le code 401 avant toute facturation.

03

Tarifs

• make_ugc à partir d’un simple script : 10 crédits par seconde de vidéo finale, arrondis à la seconde supérieure, avec un minimum de 50 crédits pour une vidéo livrée.
• make_ugc avec des segments ou des inserts : 9 crédits par seconde où un visage apparaît à l’écran (22 pour une prise rendue avec OmniHuman), plus 1 crédit par seconde de vidéo et 400 crédits pour chaque image d’appel d’avatar en direct ; minimum de 50 crédits pour une vidéo livrée. Un visage masqué par un insert, une superposition, une fenêtre ou un modèle compte quand même, et une exécution qui ne livre aucun fichier ne coûte absolument rien. Le temps de présence des visages est cumulé sur toute la vidéo et arrondi une seule fois, et non par segment. Ces champs nécessitent l’accès long format ; si celui-ci est désactivé, ils sont refusés par nom avant toute facturation.
• create_actor avec une qualité medium : 4 crédits pour le portrait (aucun si vous fournissez votre propre image dans portrait ; 4 pour une vue d’un acteur existant créée avec from_actor_id) et 8 pour chaque format supplémentaire.
• create_actor avec une qualité high : 45 crédits pour le portrait (aucun si vous fournissez votre propre image dans portrait ; 12 pour une vue d’un acteur existant créée avec from_actor_id) et 18 pour chaque format supplémentaire.
• make_faceless : 7 crédits par image générée, 49 pour le clip d’ouverture et 1 par seconde de vidéo livrée, avec un minimum de 50. Le devis pour votre durée duration_seconds représente le montant maximal à payer : 212 pour 30 secondes, 356 pour 90. Vos propres images ne sont pas facturées, et les sous-titres ne changent pas le prix.
• Les crédits s’achètent par packs : 1 000 crédits pour 10,00 $, 2 750 crédits pour 25,00 $, 6 000 crédits pour 50,00 $. Un pack par paiement, sans abonnement.

Demandez un devis avant de dépenser : le point de terminaison de devis de chaque compétence ne facture rien. La valeur de sa réponse varie selon la compétence.

• make_ugc : le devis est une estimation calculée à partir des mots du script. La facturation dépend des mesures de la vidéo finale — sa durée pour le tarif au script simple, ses secondes de présence de visages pour le tarif au visage — et peut donc être supérieure ou inférieure au devis.
• create_actor : le devis couvre tous les formats demandés et représente le montant maximal à payer. Vous êtes facturé pour le portrait et les variantes effectivement publiées ; tout format non produit est indiqué dans warnings[] et ne coûte rien.
• make_faceless : le devis couvre la durée duration_seconds demandée et représente le montant maximal à payer. La vidéo dure le temps nécessaire à la narration, au moins 25 secondes (pour un explicatif, la durée de la narration seule), et généralement au plus un quart de plus que cette durée et 90 secondes ; une narration plus longue va jusqu’à son terme. Vous êtes facturé selon la durée effectivement livrée, sans jamais dépasser le devis.

Le coût d’une exécution échouée varie également selon la compétence :

• make_ugc à partir d’un simple script : une exécution qui échoue après la commande de la vidéo est facturée. Une exécution qui échoue avant cette étape ne coûte rien, pas plus qu’une exécution que nous avons nous-mêmes arrêtée, perdue ou refusée. Avec le tarif au visage, aucun échec n’est facturé.
• create_actor : une exécution échouée ne coûte absolument rien, car aucun acteur ne vous a été livré.
• make_faceless : une exécution échouée ne coûte rien, y compris si nous l’arrêtons nous-mêmes parce qu’une étape n’a pas satisfait à nos vérifications. Une exécution mise en attente pour examen conserve la retenue de crédits jusqu’à sa résolution.

04

Tarifs des modifications

La révision d’une vidéo sans visage est une nouvelle exécution créée à partir d’un document modifié : POST /v1/runs/{id}/revisions/quote en calcule le prix gratuitement, et POST /v1/runs/{id}/revisions la lance.

• Nouvelle image : 7 crédits.
• Nouveau clip d’ouverture : 49 crédits.
• Nouvelle image fixe d’ouverture et son clip : 56 crédits.
• Rendu d’une révision qui génère quelque chose : 13 crédits, une fois par révision.
• Rendu d’une révision qui ne génère rien (un changement de rythme, une suppression ou votre propre téléversement) : 13 crédits.
• Une fois les modifications payantes activées, un original peut être modifié contre paiement pendant 364 jours après sa finalisation.
• Révisions simultanées d’un même original : 1 au maximum. Échouées ou inachevées : 3 au maximum.
• Une révision livrée est facturée au total indiqué dans son devis ; une révision échouée ne coûte rien.
• Lorsque les modifications payantes sont désactivées, les deux routes de révision répondent editing_disabled et ne facturent rien.

05

Tarifs des plans candidats

Un plan candidat est une image ou un clip créé pour un plan d’une vidéo sans visage, à conserver ou à supprimer lors d’une révision : POST /v1/runs/{id}/candidates/quote en calcule le prix gratuitement, et POST /v1/runs/{id}/candidates le crée.

• Image candidate : 7 crédits.
• Clip d’ouverture candidat : 49 crédits.
• Image fixe d’ouverture candidate et son clip : 56 crédits.
• Plans candidats simultanés d’un même original : 1 au maximum. Échoués ou inachevés : 3 au maximum. Les révisions sont comptabilisées séparément.
• Un plan candidat livré est facturé à son tarif unitaire, qu’il soit conservé ou supprimé ; un plan candidat échoué ne coûte rien.
• Lorsque les plans candidats sont désactivés, les trois routes de plans candidats répondent editing_disabled et ne facturent rien.

06

Points de terminaison

Endpoint	Coûte des crédits	Fonction
POST /v1/skills/make_faceless/quote	non	Calcule le prix d’un appel make_faceless avec ces données. Ne facture rien.
POST /v1/skills/make_faceless/run	oui	Lance une génération de vidéo sans visage et répond immédiatement avec un run_id. Interrogez la génération pour obtenir le résultat.
GET /health	non	Vérifie que l’API elle-même est opérationnelle. Répond sans clé.
GET /	non	Indique le nom du service et renvoie vers ce document. Répond sans clé.
GET /robots.txt	non	Indique aux robots d’indexation de ne pas indexer l’hôte de l’API. Répond sans clé.
GET /openapi.json	non	Description OpenAPI 3.1 de cette API, générée à partir des mêmes schémas que ceux utilisés pour valider les requêtes de l’API. Répond sans clé.
GET /v1/voices	non	Voix que vous pouvez indiquer dans voice ou voice_id pour make_ugc ; skill=make_faceless répertorie plutôt les voix de narration de make_faceless.
GET /v1/template-sounds	non	Sons diffusés par les modèles make_ugc, par temps fort : emplacement de diffusion de chaque temps fort, valeur par défaut et tous les noms acceptés par template_sounds. Gratuit.
GET /v1/moves	non	Catalogue des mouvements à appliquer aux lignes d’un script avec make_ugc, make_faceless et une recréation de référence : effet de chacun sur le spectateur, lignes auxquelles il s’applique et crédits par utilisation ; résultats filtrés et paginés. names fournit les lignes complètes. Gratuit.
GET /v1/account	non	Solde, dette et crédits réservés du compte associé à la clé, ainsi que nos réponses à ses demandes d’assistance et commentaires.
POST /v1/skills/make_ugc/quote	non	Calcule le prix d’un appel make_ugc avec ces données. Ne facture rien.
GET /v1/runs/{id}	non	État d’une génération, quelle que soit la compétence, ses avertissements et l’URL de sa vidéo.
GET /v1/runs/{id}/shots	non	Plans d’une génération : durée, paroles, description et aperçu de chaque plan, et indication précisant si la génération peut être modifiée.
GET /v1/runs/{id}/edit	non	Brouillon enregistré d’une modification d’une génération, avec sa version. La version 0 correspond à une génération sans brouillon : son document ne change rien.
POST /v1/runs/{id}/edit	non	Enregistre le brouillon d’une modification en fonction de la version consultée. Ne facture rien et ne lance aucun rendu.
POST /v1/runs/{id}/revisions/quote	non	Calcule le prix d’une révision d’une génération sans visage : ce que génère le document ou la liste des modifications de plans, et son coût. Ne facture rien. Une révision livrée est facturée au total indiqué ; une révision échouée n’est pas facturée. Tant que les modifications payantes sont désactivées, répond editing_disabled.
POST /v1/runs/{id}/revisions	oui	Lance une révision, une nouvelle génération sans visage créée à partir du document, et réserve les crédits indiqués. Une même Idempotency-Key avec la même requête renvoie la première révision ; une autre clé lance une autre révision, facturée à nouveau. Une révision livrée est facturée au total indiqué ; une révision échouée n’est pas facturée. Tant que les modifications payantes sont désactivées, répond editing_disabled et ne facture rien.
POST /v1/runs/{id}/candidates/quote	non	Calcule le prix d’un plan candidat d’une génération sans visage : une image ou un clip créé pour un plan, à conserver ou à supprimer. Ne facture rien. Un candidat livré est facturé à hauteur d’une unité, qu’il soit conservé ou supprimé ; un candidat échoué n’est pas facturé. Tant que les plans candidats sont désactivés, répond editing_disabled.
POST /v1/runs/{id}/candidates	oui	Lance un plan candidat et réserve le prix d’une unité. Un candidat livré est facturé à hauteur d’une unité, qu’il soit conservé ou supprimé ; un candidat échoué n’est pas facturé. Une même Idempotency-Key avec la même requête et le même take renvoie le premier candidat ; take + 1 en crée un autre, facturé à nouveau. Tant que les plans candidats sont désactivés, répond editing_disabled et ne facture rien.
GET /v1/runs/{id}/candidates	non	Plans candidats de la famille d’une génération sans visage, du plus ancien au plus récent, avec l’état, le coût et un aperçu dès qu’il est disponible. Tant que les plans candidats sont désactivés, répond editing_disabled.
DELETE /v1/runs/{id}/media	non	Supprime les fichiers d’une génération terminée : aucun lien ne permet désormais d’y accéder et ils sont effacés du stockage après 7 jours. La génération et son coût sont conservés. Refusé avec run_media_in_use tant qu’une autre génération non terminée les utilise. Gratuit.
POST /v1/skills/make_ugc/run	oui	Lance une génération vidéo et répond immédiatement avec un run_id. Interrogez la génération pour obtenir le résultat.
GET /v1/public/skills	non	Catalogue des compétences et de leurs données d’entrée, sans clé.
GET /v1/public/prices	non	Prix de chaque action en crédits : nombre fixe par unité ou formule dont le prix dépend des données d’entrée ; le devis indique le montant exact. Gratuit, sans clé.
GET /v1/actors	non	Acteurs enregistrés sur le compte, avec l’identifiant accepté par make_ugc.
GET /v1/public/actor-previews/{actor_id}/{version}/{file}	non	Image PNG d’un acteur de la bibliothèque, accessible via le lien fourni par list_actors et les devis. Répond sans clé.
DELETE /v1/actors/{id}	non	Supprime un acteur enregistré. Un acteur utilisé par une génération en cours est conservé.
GET /v1/actors/{id}/defaults	non	Consulte la politique par défaut de l’acteur enregistré concernant les personnes dans les inserts.
POST /v1/actors/{id}/defaults	non	Définit la politique par défaut de l’acteur enregistré concernant les personnes dans les inserts. Une génération peut la remplacer.
GET /v1/brand-kit	non	Consulte le design enregistré du compte : couleurs, polices, logo, coins et animations. Null si aucun design n’est enregistré.
POST /v1/brand-kit	non	Enregistre le design du compte ou l’efface avec null. Une vidéo qui ne précise ni design ni template_theme utilise ce design. Gratuit.
POST /v1/brand/extract	non	Récupère les couleurs, polices, le logo et les coins d’un site public pour proposer un design avec du texte lisible, à confirmer par vos soins. Gratuit ; compte dans la limite horaire de téléchargements d’URL.
POST /v1/skills/create_actor/quote	non	Calcule le prix d’un appel create_actor avec ces données. Ne facture rien.
POST /v1/skills/create_actor/run	oui	Lance une génération d’acteur et répond immédiatement avec un run_id. Interrogez la génération pour obtenir le résultat.
POST /v1/uploads	non	Reçoit des données d’image et renvoie une URL https signée, un upload_id et un content_digest (SHA-256 des données d’origine). Utilisez upload_id comme asset_id dans un workflow et copiez directement content_digest ; les appels vidéo natifs et les appels d’acteur utilisent url.
GET /v1/uploads	non	Téléversements encore acceptés par une révision, du plus récent au plus ancien et à raison d’un par image, chacun avec son upload_id, le content_digest d’origine, une URL fraîchement signée et la date à laquelle il cesse d’être utilisable. Gratuit.
POST /v1/uploads/import	non	Télécharge un PNG ou JPEG public en https (jusqu’à 10 MB, 20 secondes, 3 redirections) et renvoie la même structure de téléversement. Les adresses privées sont refusées ; 30 téléchargements par heure et par compte. Gratuit.
POST /v1/uploads/intents	non	Renvoie une URL PUT pré-signée pour un PNG ou JPEG local dont le type, la taille et le sha256 sont déclarés. L’upload_id est utilisable une fois le PUT effectué ; avant cela, les générations répondent upload_not_finished. Gratuit.
GET /v1/uploads/{id}	non	Un téléversement avec une URL fraîchement signée et son usable_until. Après un PUT pré-signé, confirme le fichier : upload_not_finished tant qu’il n’est pas disponible, upload_expired après 24 heures. Gratuit.
DELETE /v1/uploads/{id}	non	Supprime un téléversement : aucun appel ne peut désormais l’utiliser et son fichier est effacé du stockage après 7 jours, sauf si un autre téléversement de la même image est conservé. Refusé avec upload_in_use tant qu’une génération non terminée l’utilise. Gratuit.
POST /v1/assets	non	Enregistre une image comme ressource du compte, conservée jusqu’à sa suppression : à partir d’un run_id, d’un upload_id, d’une URL https publique ou de données base64. Pour votre propre contenu, rights_confirmed: true est requis, ou analysis_only: true pour une référence conservée uniquement pour analyze_reference, qu’aucun rendu ni aucune génération ne peut utiliser. 2000 ressources et 1 GB par compte, 20 GB après l’achat de crédits, 100 nouvelles ressources par jour. Gratuit.
POST /v1/assets/bytes	non	Enregistre le PNG ou JPEG du corps de la requête (jusqu’à 10 MB) comme ressource ; role, name et rights_confirmed=true (ou analysis_only=true, pour analyze_reference uniquement) sont transmis dans la requête. Gratuit.
GET /v1/assets	non	Ressources actives du compte, de la plus récente à la plus ancienne, chacune avec un lien signé valable une heure, et utilisation des limites ; filtres par role et kind, pagination par curseur. Gratuit.
GET /v1/assets/{id}	non	Une ressource active avec un lien signé valable une heure. Gratuit.
POST /v1/assets/{id}	non	Renomme une ressource ou modifie son rôle. Gratuit.
DELETE /v1/assets/{id}	non	Supprime une ressource : elle disparaît immédiatement de la liste et des générations, et un nettoyage quotidien supprime son fichier après 7 jours. Gratuit.
GET /v1/public/workflows	non	Répertorie les méthodes de workflow publiques et indique si chacune est disponible actuellement, sans tenir compte des forfaits du compte ni d’une autorisation d’accès au compte.
GET /v1/public/workflows/{id}	non	Consulte les instructions et les limites d’une méthode, ainsi que ses capacités actuelles.
POST /v1/workflow-plans	non	Crée un brouillon de workflow immuable appartenant au compte. Ne facture rien et ne lance aucun rendu.
GET /v1/workflow-plans/{id}	non	Consulte la révision actuelle du workflow du compte et son état de préparation.
POST /v1/workflow-plans/reference-remake	non	Compile un profil de référence et le script accepté dans un nouveau brouillon de recréation de référence ; ses avertissements indiquent ce que le plan ne reproduit pas. Ne facture rien, ne génère rien et ne lance aucun rendu.
POST /v1/workflow-plans/{id}/revisions	non	Enregistre un nouveau brouillon en fonction de base_version. Une nouvelle tentative identique après une réponse perdue renvoie cette révision.
POST /v1/workflow-plans/{id}/approve	non	Approuve une révision prête et son digest. Ne facture rien et ne lance aucun rendu.
POST /v1/workflow-plans/{id}/quote	non	Établit le devis d’un workflow approuvé via la préparation native. Le devis expire après cinq minutes ; aucun crédit n’est réservé. Son lancement correspond au corps prêt de la requête de génération, avec une nouvelle idempotency_key.
POST /v1/workflow-plans/{id}/run	oui	Autorise une seule fois la requête native exacte indiquée dans le devis, en renvoyant un reçu et la Run native existante. Envoyez le launch du devis sans le modifier dans le corps, avec l’en-tête Idempotency-Key égal à launch.idempotency_key ; la même requête acceptée renvoie la même génération.
GET /v1/generations/models	non	Modèles acceptés par generate_image et generate_video, avec leurs modes mesurés, formats d’image, résolutions, durées, tailles de sortie et crédits par image ou par seconde. Gratuit. Tant que les générations sont désactivées, répond generations_disabled.
POST /v1/skills/generate_image/quote	non	Calcule le prix d’une image avec cette requête : crédits, largeur, hauteur et avertissements. Ne facture rien.
POST /v1/skills/generate_image/run	oui	Lance la génération d’une image et répond immédiatement avec un run_id ; le bloc generation de la génération contient l’image une fois livrée. Une génération échouée n’est pas facturée. Tant que les générations sont désactivées, répond generations_disabled et ne facture rien.
POST /v1/skills/generate_video/quote	non	Calcule le prix d’un clip muet avec cette requête : crédits par seconde multipliés par sa durée, largeur, hauteur et avertissements. Ne facture rien.
POST /v1/skills/generate_video/run	oui	Lance la génération d’un clip et répond immédiatement avec un run_id ; le bloc generation de la génération contient le clip une fois livré. Une génération échouée n’est pas facturée. Tant que les générations sont désactivées, répond generations_disabled et ne facture rien.
POST /v1/reference-analyses/quote	non	Calcule le prix d’une analyse de cette ressource ou de ce lien : 70 crédits, 10 avec le mode data, ou 0 si l’analyse active dans ce mode fournirait une réponse. Ne facture rien.
POST /v1/reference-analyses	oui	Lance l’analyse d’une ressource MP4, jusqu’à 120 s, pour créer un profil de référence (ou, avec le mode data, sa transcription, son accroche et une planche de vignettes), et répond immédiatement ; la même ressource dans le même mode renvoie gratuitement la même analyse. Réserve 70 crédits (10 pour data), facturés une fois l’analyse réussie ; une analyse échouée ne coûte rien. 10 nouvelles analyses complètes et 60 nouvelles analyses data par heure.
GET /v1/reference-analyses/{id}	non	Une analyse de référence : en attente, en cours d’analyse, réussie avec reference_profile ou data et des avertissements, ou échouée avec son erreur. Gratuit.
POST /v1/creator-profiles/quote	non	Calcule le prix d’un profil de créateur pour ce lien : 20 crédits, ou 0 si un profil du même créateur datant de moins d’une heure fournirait une réponse. Ne facture rien.
POST /v1/creator-profiles	oui	Lance l’analyse du créateur derrière un profil Instagram ou TikTok, ou un lien vers une vidéo : ses 12 dernières vidéos avec le nombre de vues, de mentions J’aime, de commentaires et de partages, la médiane des vues et le nombre de vues de chaque vidéo par rapport à celle-ci. Répond immédiatement ; pour un même créateur dans l’heure, le même profil est renvoyé gratuitement. Réserve 20 crédits, débités uniquement en cas de réussite ; un compte privé ou vide, ou tout échec, ne coûte rien. 30 nouveaux profils par heure.
GET /v1/creator-profiles/{id}	non	Un profil de créateur : en attente, en cours d’analyse, terminé avec le profil et les avertissements, ou en échec avec son erreur. Gratuit.
DELETE /v1/creator-profiles/{id}	non	Supprime immédiatement un profil de créateur terminé ; l’exécution qui l’a créé et les frais associés sont conservés. Refusé avec run_not_finished pendant sa création. Gratuit.
POST /v1/trend-searches/quote	non	Évalue le coût d’une recherche par sujet : 20 crédits, ou 0 si une recherche portant sur la même requête au cours de la dernière heure fournirait la réponse. Aucun frais n’est débité.
POST /v1/trend-searches	oui	Lance une recherche de reels sur un sujet, en classant ensemble TikTok et Instagram, sauf si un nom de plateforme est indiqué : jusqu’à 10 reels par plateforme, un par créateur, chacun avec son nombre de vues comparé à la médiane de son créateur. Répond immédiatement ; pour une même requête dans l’heure, la même recherche est renvoyée gratuitement. Réserve 20 crédits, débités uniquement en cas de réussite, y compris si les résultats ne proviennent que d’une seule plateforme (warnings[] indique l’autre) ; aucun reel trouvé, ou tout échec, ne coûte rien. 10 nouvelles recherches par heure.
GET /v1/trend-searches/{id}	non	Une recherche par sujet : en attente, en cours, terminée avec les reels et les avertissements, ou en échec avec son erreur. sort affiche les mêmes reels dans un autre ordre. Gratuit.
POST /v1/feedback	non	Nous indique ce qui manque, prête à confusion, est incorrect ou lent, éventuellement au sujet d’une exécution de ce compte ; nous lisons chaque message. Gratuit. Un même type, texte et identifiant d’exécution dans les 24 heures renvoient le même feedback_id ; 20 par heure.
Une exécution de n’importe quelle compétence est consultée au même endroit, GET /v1/runs/{id}, et passe par les états suivants : queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

GET /v1/runs/{id}?wait_seconds=N (50 au maximum) attend que l’exécution réussisse ou échoue, que le délai d’attente expire ou que vous vous déconnectiez ; il n’est donc pas nécessaire de faire une pause entre les consultations. Une exécution inachevée répond avec son état actuel.

07

Compétences et leurs entrées

make_ugc. Lance la génération d’une vidéo UGC avec synchronisation labiale. L’acteur est défini par actor_id (un acteur enregistré provenant de list_actors) ou par image ; sinon, l’acteur par défaut est utilisé. Le format et la résolution dépendent de la requête et de la source, avec une valeur par défaut de 1080x1920. Les sous-titres sont OPT-IN : demandez d’abord à l’utilisateur. La description d’un champ que le moteur de rendu ne prend pas encore en charge indique NOT HONORED YET.

Renvoie immédiatement un run_id ; interrogez get_run avec ses poll.arguments jusqu’à ce que l’état soit 'succeeded' (video_url) ou 'failed'. Une exécution 'failed' dont la vidéo est encore en cours de création peut repasser à 'queued' et réussir plus tard ; cela est indiqué dans warnings[]. attempt=2,3,… lance une NOUVELLE exécution avec la même entrée. Pour créer une vidéo semblable à une vidéo de référence, utilisez analyze_reference, puis plan_reference_remake avec son analysis_id.

Champ	Obligatoire	Signification
script	facultatif	Les paroles prononcées par l’acteur ; obligatoire sauf si segments fournit le texte à prononcer. Les segments et les inserts ancrés au texte nécessitent une qualification long format sur le serveur. Limites du script selon le modèle vocal : eleven_v3 : 5000 caractères ; eleven_flash_v2_5 : 10000 caractères ; eleven_turbo_v2_5 : 10000 caractères ; eleven_v4 : 5000 caractères ; gemini-3.8-flash-tts : 5000 caractères. Le décompte inclut les espaces, les balises audio et les marques d’accentuation ; les emoji peuvent compter pour deux caractères. Les balises de pause sont retirées du texte envoyé à eleven_v4 et gemini-3.8-flash-tts et ne sont pas comptabilisées pour ces modèles. Il n’y a pas de limite de nombre de mots. La durée et le prix sont des estimations jusqu’à leur mesure. Accentuation en russe : écrivez la voyelle accentuée en majuscule au sein d’un mot en minuscules (« потОм », « зАмок ») ; eleven_v4 et gemini-3.8-flash-tts la reçoivent sous forme de marque d’accentuation U+0301 (« пото́м ») ; une marque saisie directement est conservée. Une majuscule en début de mot reste une majuscule, et un mot contenant une deuxième majuscule ou une consonne majuscule à l’intérieur (tout en majuscules, « ВУЗы ») reste inchangé. Une voyelle majuscule isolée à l’intérieur d’un mot est toujours interprétée comme une marque d’accentuation : écrivez donc « Яндекс Еда », et non « ЯндексЕда ». Indiquez aux utilisateurs qui écrivent en russe qu’ils peuvent marquer l’accentuation de cette façon. eleven_flash_v2_5 et eleven_turbo_v2_5 coûtent moins cher, mais interprètent mal les marques d’accentuation : les majuscules leur sont transmises sans modification.
segments	facultatif	Segments ordonnés d’acteur et d’image ; nécessite une qualification long format sur le serveur, captions=false et 1080p. Les médias image nécessitent broll_policy=anyone explicitement.
inserts	facultatif	Inserts d’image ou de vidéo ancrés au texte et superposés à l’intégralité de la narration, chacun couvrant cover_words mots prononcés à partir de son ancre ; nécessite une qualification long format sur le serveur, 1080p et broll_policy=anyone explicitement. Les sous-titres s’affichent par-dessus les inserts.
overlays	facultatif	Images ou vidéos ancrées au texte et superposées au présentateur visible, chacune à une position ou un emplacement. Au maximum 2 à l’écran simultanément, dans des cadres qui ne se chevauchent pas. Les sous-titres se déplacent vers le tiers central ou inférieur pour éviter un overlay, jamais sur le visage, et sont masqués lorsqu’aucun emplacement n’est libre. Masqués sous les inserts plein écran. Mêmes exigences que pour les inserts : script, qualification long format sur le serveur, 1080p et broll_policy=anyone explicitement. Le présentateur reste à l’écran, le prix ne change donc pas.
layout_windows	facultatif	Recadrages du présentateur ancrés au texte : split (9:16 uniquement) ou card. Les fenêtres ne peuvent se chevaucher entre elles ni chevaucher un insert. Mêmes exigences que pour les inserts. Un présentateur masqué ou flouté correspond toujours à du travail fournisseur livré et est facturé comme temps de présence à l’écran.
framing	facultatif	Tailles du présentateur ancrées au texte : chacune passe en plan rapproché ou moyen sur les mots concernés, puis revient au plan d’origine à la fin de ceux-ci. Les éléments ne peuvent se chevaucher entre eux, ni chevaucher un insert ou une fenêtre de mise en page. Un cadrage entièrement masqué par des modèles plein écran est indiqué dans warnings[]. Lorsqu’un punch_in emphasis coïncide avec un cadrage, le cadrage est appliqué. Nécessite script et une qualification long format sur le serveur ; le prix ne change pas.
templates	facultatif	Modèles graphiques, chacun { id, kind, anchor, cover_words?, placement?, transition?, data }. À chaque exécution du script. Les modèles ne changent jamais le prix : chaque exécution est facturée selon ses éléments, comme indiqué dans list_prices, et un présentateur couvert par un modèle compte toujours comme du temps de présentateur. Les identifiants sont uniques parmi inserts, overlays, layout_windows et templates. Le texte tient sur une ligne et utilise des lettres latines ou celles du script, des chiffres et des signes de ponctuation courants, sans emoji ; un glyphe CJK large compte pour 2 dans la limite, et les textes longs sont réduits pour tenir dans la largeur du type. size small|medium|large adapte l’échelle d’un type ; par défaut, la valeur est medium. Un champ media prend { asset_id } d’un élément prêt du type qu’il désigne. Une citation interne désigne des mots dans le texte propre au modèle, après le mot précédent : son temps fort tombe sur le premier mot de la citation et ne doit pas se trouver sous un insert ou un modèle plein écran ; un clic ou une étape sans citation est réparti uniformément. Un temps fort prononcé avant l’apparition du modèle est déplacé juste après son entrée, avec un avertissement. Un modèle qui chevauche la bande des sous-titres les masque pendant son affichage ; un modèle placé ailleurs, par exemple en haut en petit, les laisse visibles. Un modèle plein écran masque également le présentateur, les overlays et les modèles superposés au présentateur pendant son affichage ; il ne chevauche jamais un insert de type wipe ou zoom, et le présentateur couvert est facturé. Au maximum, 3 overlays et modèles superposés au présentateur sont affichés simultanément, sur des zones qui ne se chevauchent pas. template_theme définit l’apparence de tous ces éléments. Types : tag (over) : une courte pastille dégradée sur le présentateur ou un insert ; sans position, elle se place à l’emplacement des sous-titres et les masque pendant son affichage ; data text ≤ 32, position? top|center|bottom, size? small|medium|large. lower_third (over) : une barre de nom et de fonction dans le bas de l’image ; les sous-titres sont masqués pendant son affichage ; style vaut clean_bar par défaut ; data name ≤ 28, role? ≤ 36, side left|right, style? clean_bar|side_rule|soft_pill|mask_reveal, size? small|medium|large. end_card (over) : une pastille de site avec un appel à l’action facultatif à l’emplacement des sous-titres ; les sous-titres sont masqués pendant son affichage ; data site ≤ 32, cta? ≤ 48, size? small|medium|large. title_card (full) : une carte d’accroche plein écran : le titre (jusqu’à deux lignes) sur une carte blanche, à côté d’une image de logo facultative, avec une puce facultative en dessous ; data title ≤ 48, chip? ≤ 32, logo? {asset_id} image, size? small|medium|large. quote (full) : une carte de citation plein écran : guillemets, texte sur quatre lignes maximum, puis auteur avec une photo ronde facultative, recadrée en cercle ; data text ≤ 120, author? ≤ 32, photo? {asset_id} image (recadrée pour remplir), size? small|medium|large. stat (full|over) : un nombre qui compte de 0 à value (jusqu’à 2 décimales), encadré par un préfixe et un suffixe, avec un libellé en dessous ; full remplit l’image, over s’affiche à hauteur de poitrine sur une carte ; data value number, prefix? ≤ 6, suffix? ≤ 6, label? ≤ 32, size? small|medium|large. callout (over) : une flèche ou un cercle qui pointe vers un point de l’image et pulse, target {x,y} en % de l’image à partir du coin supérieur gauche, avec une pastille de libellé facultative en dessous ou au-dessus ; peut pointer vers le visage, et son libellé évite le visage dans la mesure du possible ; également sur un insert ; data target {x,y}, style arrow|ring, text? ≤ 24, size? small|medium|large. checklist (over) : 2–4 lignes, chacune avec une icône facultative, un libellé et un interrupteur ou une case à cocher activé ou désactivé ; un curseur clique les lignes à tour de rôle (item est l’index de la ligne à partir de 0), chaque clic change son état ; sous le visage ; data items 2–4 de {label ≤ 24, on true|false, icon? phone|briefcase|user|clock|chat|star}, clicks? 0–6 de {item number, quote? citation interne}, style? switch|check, size? small|medium|large. phone_call (over) : un appel entrant sur un téléphone neutre sur le côté (à droite, sauf si side vaut left) : l’appelant, un sous-titre et un anneau d’avatar rond, puis l’appel est décroché à answer_at et son chronomètre démarre (ou une bannière de mise en attente s’affiche) ; à côté du visage dans les images larges, en dessous dans les images hautes ; data caller ≤ 24, subtitle? ≤ 32, avatar? {asset_id} image (recadrée pour remplir), answer_at citation interne, side? left|right, size? small|medium|large, banner? ≤ 32, banner_note? ≤ 48, mask_number? true|false. compare (full) : une carte plein écran au format 3:5 affichant l’image avant ; à reveal_at, l’image après apparaît en diagonale (reveal absent) ou glisse depuis la gauche jusqu’à un séparateur central ; les deux restent visibles, avec des pastilles de libellé facultatives ; data before {asset_id} image (recadrée pour remplir), after {asset_id} image (recadrée pour remplir), labels? {before? ≤ 20, after? ≤ 20}, reveal_at citation interne, reveal? sweep|wipe, size? small|medium|large. notification (over) : une notification de téléphone en haut, au-dessus du visage : une icône (sinon, l’initiale de l’application), l’application, un titre et une ligne de texte ; elle apparaît en glissant, reste affichée au moins 1.2 s et disparaît avant la fin de sa durée ; chaque carte empilée apparaît au-dessus à son at, repoussant les précédentes vers l’arrière ; data app ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, stack? 1–2 de {app? ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, at? citation interne}, size? small|medium|large. progress (over) : 2–5 étapes en colonne sur une carte, chacune se terminant par une coche à tour de rôle, à sa citation advance_at (une par étape, dans l’ordre) ou réparties uniformément ; sous le visage ; data steps 2–5 de ≤ 20, advance_at? 2–5 citations internes, size? small|medium|large. rating (over) : cinq étoiles sur une carte qui se remplissent à tour de rôle jusqu’à stars (1–5 par demi-étoile, une demi-étoile étant à moitié remplie), avec un libellé facultatif en dessous ; à hauteur de poitrine ; data stars number, label? ≤ 32, size? small|medium|large. chat_window (full) : une fenêtre de chat plein écran : la requête est saisie, la réponse s’affiche mot par mot, son tableau s’ouvre ligne par ligne, puis les cartes de réponse apparaissent, chacune à son at ou répartie uniformément ; zoom true effectue un zoom avant et arrière sur les temps forts ; data app? ≤ 24, prompt ≤ 120, replies? 1–3 de {title ≤ 32, body? ≤ 64, at? citation interne}, answer? {text ≤ 150, at? citation interne}, table? {columns 2–3 de ≤ 16, rows 1–4 de {cells 2–3 de ≤ 20, at? citation interne}}, zoom? true|false, size? small|medium|large. video_grid (full) : une grille plein écran des vidéos du compte sous forme de vignettes 9:16, en 2x2 (cellules 1–4, la colonne de gauche étant surélevée) ou en 3x1 (cellules 1–3) ; sans layout, les cellules fournies déterminent la disposition, chaque vignette apparaissant après la précédente et étant lue sans son, avec un titre facultatif au-dessus ; data layout? 2x2|3x1, cell_1 {asset_id} video (recadrée pour remplir), cell_2 {asset_id} video (recadrée pour remplir), cell_3 {asset_id} video (recadrée pour remplir), cell_4? {asset_id} video (recadrée pour remplir), title? ≤ 40, size? small|medium|large. word_title (full) : un titre cinétique plein écran dans la couleur d’accentuation : la première entrée apparaît dès la première image du modèle, chaque entrée suivante à sa citation at (généralement les mêmes mots que ceux prononcés), ou répartie uniformément ; reveal replace (par défaut) affiche une entrée à la fois, build ajoute chaque entrée au titre ; data words 1–8 de {text ≤ 16, at? citation interne}, reveal? replace|build, size? small|medium|large. phone_screen (full) : un téléphone plein écran qui lit la vidéo d’écran (sans son ; un dégradé s’affiche en l’absence de vidéo), dont les états changent à tour de rôle, chacun à sa citation at ou réparti uniformément : lock (assombri, un cadenas et le texte), play (vidéo claire, texte en haut), liked (un cœur et le texte), counter (une pastille au bas de l’écran), timer (un badge sur son bord supérieur), tag (une puce avec une ligne de repère sur le côté de l’écran) ; lock, play et liked se remplacent mutuellement, les tags s’accumulent, un counter ou timer ultérieur remplace le précédent ; data screen? {asset_id} video (recadrée pour remplir), states 1–6 de {state lock|play|liked|counter|timer|tag, text? ≤ 24, at? citation interne}, size? small|medium|large. terminal (full) : une carte de terminal sombre plein écran : la commande est saisie ; un diff en dessous replie ses lignes del (rouges) et ouvre ses lignes add (vertes) à diff.at ; une ligne d’état cochée s’affiche ensuite à at ; title nomme la carte ; data title? ≤ 24, command ≤ 100, diff? {lines 2–7 de {text ≤ 36, change? add|del}, at? citation interne}, status ≤ 40, at? citation interne, size? small|medium|large. pointer_chips (over) : 1–4 puces en colonne sous le visage (à droite, sauf si side vaut left), chacune reliée par une ligne courbe à un point de son target {x,y} en % de l’image à partir du coin supérieur gauche ; elles apparaissent à tour de rôle à leur citation at ou sont réparties uniformément ; les lignes peuvent traverser le visage, mais les puces l’évitent ; également sur un insert ; data items 1–4 de {target {x,y}, text ≤ 20, at? citation interne}, side? left|right, size? small|medium|large. chart (full) : un graphique à barres ou en courbes plein écran, avec 2–6 points étiquetés sur une carte : à la citation at de chaque point, ou répartis uniformément, sa barre grandit ou la courbe se trace jusqu’à lui et sa valeur augmente progressivement, avec le suffixe après celle-ci ; titre au-dessus ; data type bar|line, title? ≤ 40, suffix? ≤ 6, points 2–6 de {label ≤ 12, value number, at? citation interne}, size? small|medium|large. race (full) : une course de barres classées plein écran : une barre par nom, la plus longue en haut ; les valeurs du premier tour s’affichent dès le début, puis à la citation at de chaque tour suivant, ou réparties uniformément, les barres se déplacent vers leurs nouvelles valeurs et changent de place selon leur classement, le libellé du tour s’affichant en dessous ; data title? ≤ 40, suffix? ≤ 6, names 3–6 de ≤ 14, rounds 2–5 de {label? ≤ 10, values 3–6 de number, at? citation interne}, size? small|medium|large. hand_title (full|over) : un titre écrit trait par trait dans une police manuscrite (jusqu’à deux lignes), puis un marqueur tracé sur les mots du titre à partir de mark.word (index à partir de 0) pour mark.words (1 par défaut), à mark.at ou vers la fin du modèle ; over se place à l’emplacement des sous-titres et les masque ; data text ≤ 40, mark? {word number, words? number, style highlight|underline|circle, at? citation interne}, size? small|medium|large. word_fill (full) : un seul mot géant plein écran dont les lettres affichent votre vidéo (clip, lue sans son), le reste de l’image étant le fond du thème ; il grandit pendant ses 10 premières images ; data word ≤ 10, clip {asset_id} video, size? small|medium|large.
template_theme	facultatif	L’apparence de chaque modèle de l’exécution : un préréglage et une couleur d’accentuation facultative ; uniquement avec templates.
design	facultatif	L’identité visuelle de l’exécution : templates, la carte de fin et l’accentuation des sous-titres en reprennent les éléments. Demandez la marque ou utilisez extract_brand ; par défaut, le kit de marque enregistré est utilisé. Incompatible avec template_theme.
template_sounds	facultatif	Accepté ; le schéma ne comporte pas encore de description.
scenes	facultatif	Graphismes créés pour cette vidéo à partir de vos mots, pour ce qu’aucun modèle ne représente : chacun est dessiné sur le présentateur (over) ou en plein écran (full) pendant que ses mots sont prononcés ; un graphisme qui recouvre les sous-titres les masque pendant son affichage. Tout graphisme qui ne passe pas notre vérification est omis et indiqué dans warnings[]. 25 crédits par scène, avec sa propre ligne de citation, facturés uniquement pour les scènes dessinées dans la vidéo livrée. Nécessite un script et une qualification long format côté serveur.
motion_style	facultatif	Type accepté : object.
moves	facultatif	Mouvements de list_moves appliqués à vos mots : chacun { name, anchor: { quote }, cover_words?, placement?, data? }. Chacun est dessiné comme indiqué dans sa ligne de list_moves ; data prend les champs qui y sont nommés. Tout mouvement impossible à dessiner sur les mots concernés ou dans cette vidéo est indiqué dans warnings[] et omis, jamais supprimé sans avertissement. Ses crédits figurent sur la citation.
edit_sounds	facultatif	Valeurs acceptées : true | false.
music	facultatif	Musique de fond sous la voix, créée pour cette vidéo ; désactivée sauf demande de votre part. "auto" déduit l’ambiance du script ; { mood } la décrit avec vos mots, par exemple "calm lo-fi". 60 crédits par vidéo, avec sa propre ligne sur le devis, facturés uniquement lorsque la vidéo est livrée avec la musique.
call	facultatif	Appel téléphonique après une citation : le présentateur écoute, puis se fige pendant que l’appel est diffusé comme une ligne téléphonique, précédé d’une sonnerie ; un téléphone affichant l’appel en cours apparaît à côté de lui (un modèle phone_call couvrant l’appel est utilisé à la place). Nécessite un script, une image au format 9:16 et des mots après l’appel. Le présentateur figé et l’appel ajoutent des secondes de production, et non des secondes de présentateur ; un avatar animé encore affiché pendant l’appel a son propre prix dans list_prices. Qualification long format côté serveur.
interview	facultatif	Une interview : un intervenant hors champ prononce les mots du script marqués, avec sa propre voix ; le présentateur répond au reste à l’écran et reste immobile pendant que l’intervenant hors champ parle. Nécessite un script et l’autorisation long format sur le serveur ; les images fixes du présentateur ajoutent des secondes de production, pas des secondes de présentateur.
presenter_gaze	facultatif	Direction du regard du présentateur pendant ces mots, du point de vue du spectateur : caméra, gauche ou droite. Nécessite actor_id avec cette vue (list_actors) ; un changement de regard constitue une coupe.
shots	facultatif	Plans en direct de l’acteur sur certains mots du script : talking, talking_action (parle tout en agissant) ou action (agit pendant que les mots sont diffusés en voix off). Les plans ne peuvent pas se chevaucher ; en dehors de ces plans, les mots sont interprétés dans la prise habituelle du présentateur. Nécessite un format 9:16 et l’autorisation long format sur le serveur ; chaque type a son propre tarif par seconde de présentateur dans list_prices.
product_asset_id	facultatif	Image du produit (ast_…) affichée dans les plans avec le produit.
person	facultatif	PAS ENCORE PRIS EN CHARGE : person n’est pas encore pris en charge : cette requête utilise l’acteur par défaut ; choisissez actor_id dans list_actors ou fournissez une image pour sélectionner un autre visage
actor_id	facultatif	ID d’acteur Clipwright enregistré, issu de list_actors. Choisissez actor_id, image ou person ; ne les combinez pas. Sans voice ni voice_id, la voix correspond au genre de l’acteur. Ne pas combiner avec actor_gender.
presenter_framing	facultatif	close (par défaut), wide (présentateur plus bas, pièce visible au-dessus) ou full (de la tête aux pieds). Nécessite la vue de l’acteur portant ce nom (list_actors), uniquement en 9:16 ; full passe à wide, puis à close, avec des avertissements[].
presenter_mic	facultatif	true : le présentateur tient un petit micro. Nécessite la vue de l’acteur avec micro pour ce cadrage (list_actors ; les vues de la bibliothèque sont wide) ; sinon, pas de micro et avertissements[].
image	facultatif	URL https publique de la photo de l’acteur (PNG, JPEG ou WebP, jusqu’à 10 MB). Un fichier sur disque doit d’abord être envoyé via upload_image (POST /v1/uploads) — transmettez l’url renvoyée. Une source inutilisable — hôte privé ou de bouclage, http, inaccessible, avec redirection, dépassant 10 MB ou d’un type d’image non pris en charge — est refusée (unusable_source) avant tout débit. Nous ne détectons pas le genre du visage : transmettez actor_gender ou voice, sinon la voix masculine par défaut est utilisée avec un avertissement.
actor_gender	facultatif	Genre du visage dans image : female | male. Uniquement avec image : sélectionne la voix par défaut de ce genre (female : sarah, male : george ; sur gemini-3.8-flash-tts : kore et charon). Refusé avec actor_id (son genre est connu) et sans image. Une valeur voice ou voice_id explicite prévaut et la réponse indique que actor_gender n’a rien changé.
name	facultatif	PAS ENCORE PRIS EN CHARGE : name n’est pas encore pris en charge : il n’est pas transmis au moteur de rendu
broll_policy	facultatif	Politique pour les plans d’illustration : anyone autorise les personnes, y compris l’acteur ; no_actor exclut l’acteur ; no_people exclut toutes les personnes, y compris les mains. Les modèles avec votre propre image ou vidéo nécessitent « anyone » ; sinon, la valeur est uniquement enregistrée. La valeur de remplacement de l’exécution prévaut sur la valeur par défaut de l’acteur du compte ; sinon, no_people.
captions	facultatif	Incruster dans la vidéo des sous-titres synchronisés mot à mot, par-dessus le présentateur et les inserts. Non disponible avec segments.
caption_style	facultatif	Apparence des sous-titres lorsque captions=true. hormozi : style par défaut : majuscules blanches épaisses avec un contour noir épais, jusqu’à trois mots par segment, un mot-clé par segment en jaune (mot mis en évidence, sinon le mot le plus long qui n’est pas un mot vide). accent : majuscules blanches grasses et condensées, sans contour, jusqu’à trois mots par segment, un mot-clé par segment en orange (mot mis en évidence, sinon le mot le plus long qui n’est pas un mot vide). tiktok : majuscules grasses et arrondies, un ou deux mots à la fois ; le mot prononcé devient jaune et s’agrandit. youtube : sans-serif gras et lisible, quatre mots (cinq en 16:9) sur un encadré sombre arrondi près du bas ; les mots apparaissent en fondu, le mot prononcé en rouge. instagram : majuscules façon bande dessinée avec un contour rose, deux mots à la fois ; le mot prononcé apparaît en orange. minimalist : sans-serif simple, quatre mots sur une bande sombre semi-transparente, fondu doux. neon : majuscules cyan avec un contour magenta, deux mots à la fois ; le mot prononcé apparaît en blanc. genz : grandes majuscules façon bande dessinée, un mot à la fois, qui surgit avec un surlignage rose. campfire : majuscules arrondies façon bande dessinée, trois mots ; les mots prononcés s’illuminent en doré et le restent. midnight : majuscules inquiétantes, deux mots, fondu lent ; le mot prononcé en rouge. plottwist : sans-serif épais, trois mots ; le mot prononcé devient bleu ciel et s’agrandit. headline : majuscules hautes et condensées sur une bande noire unie, trois mots ; le mot prononcé s’agrandit en jaune. promo : sans-serif épais sur une pastille bleue, trois mots ; le mot prononcé apparaît en jaune. lecture : sans-serif lisible, quatre mots sur un encadré sombre arrondi ; le mot prononcé en vert. highlighter : sans-serif épais, quatre mots ; les mots prononcés deviennent vert citron et le restent. studio : sans-serif, quatre mots qui s’écrivent sur un encadré sombre flou ; le mot prononcé en ambre. broadcast : sans-serif avec contour, quatre mots dans le bas de l’image ; le mot prononcé en jaune pâle. arcade : majuscules jaunes anguleuses, deux mots ; le mot prononcé rebondit en blanc. clutch : majuscules façon pinceau, un mot à la fois, qui surgit en vert. bubblegum : lettres d’affichage arrondies avec un contour rose, deux mots ; le mot prononcé rebondit en jaune. crayon : écriture manuscrite au marqueur avec un contour bleu marine, deux mots ; le mot prononcé apparaît en orange. lyrics : écriture manuscrite, quatre mots ; les mots prononcés s’illuminent en rose et le restent. bassdrop : majuscules d’affichage avec contour, un mot à la fois, qui s’agrandit en orange. punch : mise en place et chute au milieu de l’image : une petite ligne d’introduction blanche au-dessus d’un ou deux grands mots-clés bleus lumineux ; les autres mots sont petits et blancs. Alias : minimal produit le style minimalist. Si une police ne peut pas afficher les lettres du script, elle est remplacée par une police sans-serif simple. Aperçus : https://clipwright.io/captions
caption_emphasis	facultatif	Mots-clés ou courtes expressions à mettre en évidence, chacun cité du script et correspondant à une citation d’insert (casse et ponctuation ignorées). Un élément est soit la citation, soit { quote, look } : look punch affiche une petite ligne d’introduction de la même phrase au-dessus de la citation, présentée comme un grand mot-clé lumineux ; look pill affiche uniquement la citation dans une pastille arrondie ; look color l’affiche dans la couleur d’accentuation, à la même taille ; look box l’affiche sur un encadré doux de la couleur d’accentuation, à la même taille. Sans look, punch produit le style punch, hormozi et accent produisent le style color, et les autres préréglages affichent la citation en plus grand dans leur couleur de mise en évidence. Chaque occurrence est mise en évidence. Nécessite captions=true et un script ; une citation absente du script est refusée avant tout débit.
caption_mode	facultatif	full (par défaut si omis) : chaque mot prononcé est sous-titré. highlights : les sous-titres apparaissent uniquement autour des citations caption_emphasis (introduction, citation, courte suite) et nulle part ailleurs ; nécessite caption_emphasis. Dans les deux modes, les sous-titres sont masqués lorsqu’un insert plein écran est affiché ou qu’un modèle recouvre leur bande.
caption_position	facultatif	Position des sous-titres : top, middle, lower ou bottom (80 % de la hauteur). Si omis, les sous-titres sont placés à l’emplacement propre à caption_style. Nécessite captions=true.
caption_place	facultatif	À la place de caption_position, les sous-titres restent à leur hauteur propre ; les superpositions ne les déplacent jamais, et toute superposition qui les recouvre est refusée, sauf si elle est placée relative_to captions. Nécessite captions=true.
presenter_place	facultatif	Hauteur et position centrale du visage du présentateur dans l’image. Le portrait est cadré plus serré pour atteindre cette position, à partir de la vue wide de l’acteur lorsque la vue close est trop rapprochée ; si même cette vue est trop rapprochée, warnings[] indique la hauteur du visage affichée. Nécessite actor_id et un script avec overlays, inserts, layout_windows, framing ou call. Le prix ne change pas.
look	facultatif	PAS ENCORE PRIS EN CHARGE : look n’est pas encore pris en charge : il n’est pas transmis au moteur de rendu
aspect_ratio	facultatif	Format de sortie : 9:16 | 1:1 | 16:9. Si omis, 9:16 sans image ; avec une image, le format pris en charge le plus proche des proportions de l’image, même si elle est en paysage — indiquez-le explicitement chaque fois que vous transmettez image. Un écart supérieur à 15 % entre la demande et la source est refusé (aspect_conflict) avant tout débit.
resolution	facultatif	Résolution de sortie : 720p | 1080p (côté court de 720 / 1080 px). Si omis, 1080p.
voice	facultatif	Nom de voix issu de list_voices. Préréglages sélectionnés : sarah | george | eric | daria_ru_female. L’API refuse avant tout débit un nom que list_voices ne renvoie pas. Si omis, la voix par défaut correspondant au genre de l’acteur est utilisée : genre de actor_id, actor_gender avec image, ou george pour l’acteur par défaut et pour image sans actor_gender. gemini-3.8-flash-tts ne parle qu’avec ses propres voix (kind model_voice dans list_voices, comme kore) : en nommer une sélectionne ce modèle, et une voix est refusée avant tout débit avec un tts_model qui ne la prend pas en charge. Mutuellement exclusif avec voice_id.
voice_id	facultatif	ID de voix brut du fournisseur (16–32 lettres et chiffres) pour une voix hors catalogue. Vérification différée : un ID inconnu fait échouer l’exécution, pas la requête. Refusé avec tts_model=gemini-3.8-flash-tts. Mutuellement exclusif avec voice.
tts_model	facultatif	Modèle vocal : eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5 | eleven_v4 | gemini-3.8-flash-tts. Si omis, le modèle de la voix choisie est utilisé (list_voices l’indique) : gemini-3.8-flash-tts pour ses propres voix, eleven_v4 pour chaque préréglage, voix du catalogue et voice_id brut. Un tts_model explicite prévaut, sauf eleven_v3 : il n’est plus utilisé pour la synthèse vocale, et une exécution qui le nomme utilise eleven_v4 avec un avertissement. eleven_v4 et gemini-3.8-flash-tts interprètent les marques d’accent tonique (une voyelle majuscule dans un mot russe, « потОм », devient un ; voir script) ; eleven_flash_v2_5 et eleven_turbo_v2_5 sont des solutions moins coûteuses pour les langues autres que le russe. gemini-3.8-flash-tts ne parle qu’avec ses propres voix (list_voices avec model=gemini-3.8-flash-tts ; sans voice, kore pour un acteur féminin et charon sinon) et ne renvoie pas de minutages par mot : un préréglage ou une voix du catalogue, voice_id, captions=true, segments et inserts sont refusés avec ce modèle avant tout débit. Les balises audio entre crochets sont une convention des autres modèles vocaux et ne sont pas mesurées par celui-ci. Limites de script selon le modèle vocal : eleven_v3 : 5000 caractères ; eleven_flash_v2_5 : 10000 caractères ; eleven_turbo_v2_5 : 10000 caractères ; eleven_v4 : 5000 caractères ; gemini-3.8-flash-tts : 5000 caractères. Le décompte inclut les espaces, les balises audio et les marques d’accent tonique ; les emoji peuvent compter pour deux caractères. Les balises de pause sont retirées du texte envoyé à eleven_v4 et gemini-3.8-flash-tts et ne sont pas comptabilisées pour ces modèles. Il n’y a pas de limite de nombre de mots. La durée et le prix sont des estimations jusqu’à leur mesure.
voice_pace	facultatif	Vitesse de narration ; 1 correspond à la vitesse propre de la voix. gemini-3.8-flash-tts reçoit plutôt une indication de style ; eleven_v4 n’a pas de réglage de vitesse, choisissez donc une voix selon les mots_par_seconde indiqués par list_voices ; les deux sont mentionnés dans warnings[].
pause_trim	facultatif	Couper les pauses dépassant ces s ; false conserve toutes les pauses. Valeur par défaut avec les modèles, scènes et plans : 0.15 pour les phrases, 0.08 pour les virgules.
end_hold_s	facultatif	Nombre de secondes pendant lesquelles la dernière image reste affichée après le dernier mot : le présentateur se fige et toutes les couches à l’écran restent alors affichées. Secondes de production, pas secondes de présentateur. Nécessite un script et l’autorisation long format.
visible_ai_label	facultatif	Mention IA visible pour les nouvelles vidéos de présentateur marquées, y compris en long format ; activée par défaut dans la politique d’admission du serveur. false masque uniquement la mention visible et ne désactive ni le marquage invisible ni la provenance signée. Les sorties historiques ne sont pas modifiées.
background	facultatif	Valeurs acceptées : white | blur | contain.
create_actor. Créez un acteur personnel pour ce compte à partir de mots décrivant un adulte fictif : un portrait au format 9:16 avec exactement un visage, ainsi que les autres formats demandés, retouchés à partir de celui-ci. Renvoie immédiatement un run_id ; interrogez get_run jusqu’à ce que le statut soit 'succeeded' (created_actor.actor_id, puis transmettez-le comme actor_id à make_ugc) ou 'failed'. Chaque image publiée est facturée au prix indiqué par le devis ; les descriptions refusées et les portraits inutilisables ne coûtent rien. Lorsque la génération est désactivée, l’appel échoue avec actor_generation_disabled. from_actor_id conserve le visage (vérifié ; une différence ne coûte rien). Avec style_reference, un portrait ressemblant à une personne sur la photo est refusé sans frais, et le prix reste le même. portrait (avec gender et approximate_age) devient le portrait au format 9:16 sans frais ; seuls les autres formats sont facturés. Une image sans exactement un visage, ou dont le visage est coupé, trop petit ou trop grand, est refusée sans frais. Une mascotte de marque dessinée avec generate_image peut servir de portrait si son visage ressemble à un visage humain (une personne de dessin animé) ; une mascotte animale ou représentant un objet est refusée : montrez-la plutôt dans des inserts.

Field	Required	What it means
description	optional	Mots décrivant un adulte fictif : apparence, vêtements, décor. La mention d’une personne réelle ou d’une ressemblance avec une personne réelle est refusée avant toute facturation (actor_prompt_refused). Obligatoire sauf si from_actor_id ou portrait est fourni ; avec from_actor_id, l’apparence, les vêtements et la pose de la vue changent, tandis que le genre et l’âge restent ceux de la source.
gender	optional	female | male. Définit le genre de l’acteur et la voix par défaut des vidéos avec cet acteur. Obligatoire sauf si from_actor_id est fourni.
approximate_age	optional	Âge approximatif en années, de 18 à 90 : les acteurs sont des adultes. Obligatoire sauf si from_actor_id est fourni.
name	required	Nom affiché dans list_actors.
aspect_ratios	optional	Formats à créer : 9:16 | 1:1 | 16:9, avec toujours le 9:16. Si omis, les trois formats sont créés. Les formats qui échouent à la vérification d’identité ne sont pas facturés et sont indiqués dans warnings.
from_actor_id	optional	Créez un nouvel acteur personnel à partir de celui-ci (un acteur de la bibliothèque ou le vôtre) : même visage, même genre et même âge, avec une vue modifiée par le cadrage, les objets tenus, le décor, la description ou style_reference. Omettez gender et approximate_age.
framing	optional	Taille du plan : close (par défaut, poitrine cadrée), wide (de la taille vers le haut, mains visibles, espace au-dessus de la tête) ou full (debout, de la tête aux pieds). À partir de mots, ce paramètre définit le cadrage du nouveau portrait ; avec from_actor_id, wide ou full éloigne la caméra. La vue est classée selon la taille du visage représenté, et make_ugc la génère avec presenter_framing de ce nom. Incompatible avec style_reference ou portrait, dont l’image définit le cadrage.
holding	optional	Jusqu’à 2 objets tenus par la personne, un dans chaque main.
setting	optional	La pièce ou l’arrière-plan où placer la personne, décrit en mots.
style_reference	optional	Photo PNG ou JPEG dont le décor, l’éclairage, l’angle de caméra, la taille du plan et les vêtements seront repris dans le nouveau portrait : cadrage poitrine, taille ou pleine hauteur, comme sur la photo ; un portrait plus large qu’un cadrage poitrine devient une vue wide. Image asset de ce compte (téléversement, importation par URL ou image trouvée, rights_confirmed). Sans from_actor_id, le visage est nouveau et créé à partir de description ; avec ce paramètre, le visage est celui de l’acteur source. Un portrait ressemblant à une personne sur la photo est refusé sans frais.
portrait	optional	Créez l’acteur à partir de votre propre image de portrait au lieu d’en générer une : image PNG ou JPEG de ce compte (rights_confirmed), avec un rapport d’aspect à 9:16 à 2 % près, montrant exactement un visage qui n’est ni coupé, ni trop petit, ni trop grand. Elle devient le portrait 9:16 de l’acteur sans frais ; les autres formats sont retouchés à partir de celui-ci et facturés normalement. À utiliser avec gender et approximate_age ; incompatible avec description, style_reference ou from_actor_id.
quality	optional	Qualité de l’image : medium | high. Si omis, medium est utilisé. high produit le portrait le plus naturel. Le prix par image dépend de ce paramètre ; le devis l’indique avant toute facturation.

make_faceless. Lancez la création payante d’une vidéo faceless terminée à partir d’un script ou d’un brief. Vous choisissez une durée de 30 à 90 secondes ; la vidéo se termine avec sa narration, dure au moins 25 secondes (pour un explainer, aussi longtemps que sa narration) et au plus un quart de plus que la durée choisie, sans jamais dépasser 90 secondes. La vidéo comprend un clip d’ouverture animé et des scènes illustrées. Les sous-titres sont activés par défaut et peuvent être désactivés.

La méthode renvoie immédiatement un run_id ; interrogez get_run avec ses poll.arguments jusqu’à ce que le statut soit 'succeeded' (video_url) ou 'failed'. attempt=2,3,… lance une NOUVELLE exécution pour la même entrée.

Field	Required	What it means
input_mode	required	'script' lit votre texte exact ; 'brief' rédige la narration à partir d’une courte description. Envoyez exactement l’un des champs script ou brief, conformément à ce mode.
script	optional	La narration, lue telle qu’elle est écrite. Obligatoire lorsque input_mode est 'script' ; doit être absent lorsque input_mode est 'brief'.
brief	optional	Sujet de la vidéo ; la narration est rédigée à partir de celui-ci. Obligatoire lorsque input_mode est 'brief' ; doit être absent lorsque input_mode est 'script'.
duration_seconds	required	Durée choisie, de 30 à 90 secondes, sur une limite d’image de 1/25 s. La vidéo se termine avec sa narration et dure au moins 25 secondes (pour un explainer, aussi longtemps que sa narration), généralement au plus un quart de plus que la durée choisie et 90 secondes ; si la narration est plus longue, la vidéo va jusqu’à sa fin. Une vidéo qui dépasse la durée choisie de plus de 5 secondes le signale dans warnings[]. Le montant facturé ne dépasse jamais le devis. Un script est accepté si sa durée estimée est comprise entre 21 secondes et la durée choisie plus 5 secondes, sans dépasser 90 secondes.
style_reference	optional	Image publique en https dont le style visuel est repris dans les scènes.
character_reference	optional	Image publique en https d’une personne ou d’un personnage à garder cohérent dans toutes les scènes.
character_details	optional	Détails visuels fixes de cette personne ou de ce personnage, comme les cheveux, les vêtements et les accessoires absents ; conservés dans chaque scène générée.
scene_images	optional	Vos images, chacune placée à une plage de mots ou à une citation de la narration.
captions	optional	Sous-titres incrustés ; activés par défaut.
transitions	optional	Flash ou fuite de lumière sur les coupes, avec son : à chaque changement de scène, ou au changement le plus proche de chaque ancre (script uniquement). Si omis pour un brief : flash à chaque changement de scène ; false pour des coupes simples. Aucun supplément.
edit_sounds	optional	Son discret à chaque changement de scène, avec un pic sur la coupe ; template_sounds.edit le sélectionne. Prix inchangé.
template_sounds	optional	false pour aucun son, ou { flash, whoosh (fuite de lumière), edit: name } parmi les résultats de list_template_sounds.
music	optional	Musique de fond sous la voix, créée pour cette vidéo ; désactivée sauf demande de votre part. "auto" déduit l’ambiance du script ; { mood } la décrit avec vos mots, par exemple "calm lo-fi". 60 crédits par vidéo, indiqués sur une ligne distincte du devis et facturés uniquement si la vidéo est livrée avec la musique.
templates	optional	Script uniquement : comme pour make_ugc, un emplacement peut afficher votre image ou votre vidéo (asset_id, rights_confirmed). Gratuit.
shots	optional	Script uniquement : 1 à 10 {id, anchor, action, asset_id?}, 5 s maximum chacun.
scenes	optional	Script uniquement : comme les scènes de make_ugc.
motion_style	optional	Comme motion_style de make_ugc ; s’applique à tout le script. Gratuit.
moves	optional	Script uniquement : mouvements de list_moves associés à vos mots : chacun { name, anchor: { quote }, cover_words?, placement?, data? }. Chaque mouvement est représenté comme indiqué dans sa ligne de list_moves ; data contient les champs qui y sont nommés. Un mouvement impossible à représenter sur les mots associés ou dans cette vidéo est indiqué dans warnings[] et omis, jamais supprimé sans avertissement. Son coût en crédits figure dans le devis.
format	optional	'explainer' : dessin animé explicatif, un événement à chaque mot, un personnage principal dans un coin ; script uniquement. Ce format convient à une suite d’actions concrètes racontées par une seule voix : tutoriel étape par étape, explication du fonctionnement d’un objet, flux de travail, présentation d’un outil, N erreurs ou N façons de faire, avec quelque chose à montrer pour chaque phrase. Un raisonnement sans actions, un dialogue ou une histoire mettant en scène des personnes s’y prête mal. Chaque devis de script indique explainer_fit : proposez ce format lorsqu’il convient ; sinon, indiquez pourquoi et reformulez le script sous forme d’actions avant de demander confirmation. Le personnage principal est dessiné à partir de character_reference ou character_details (sa pose est illustrée dans le devis), sinon à partir du nôtre, gratuitement. Une liste d’éléments nommés est illustrée par une image de chaque élément dans sa scène, une par élément dans le devis, facturée uniquement lorsqu’elle est affichée. Sans voix, un script en anglais est lu par notre voix la plus rapide.
pause_trim	optional	Script uniquement : comme pause_trim de make_ugc, avec le même comportement par défaut avec templates, scenes, shots ou le format explainer.
voice	optional	Voix de narration : un nom de list_voices avec skill=make_faceless (kind faceless_voice). Si omis, narrator_en_wise_lady est utilisé ; pour un explainer en anglais, la voix la plus rapide. Choisissez une voix dans la langue de la narration : une voix peut lire n’importe quelle langue, avec son propre accent. L’API refuse un nom inconnu et une voix make_ugc avant toute facturation. Un voice_id brut n’est pas accepté ici.

• Une vidéo faceless ne comporte aucun présentateur à l’écran : la narration accompagne un clip d’ouverture animé et des scènes illustrées. Envoyez exactement l’un des champs script et brief, celui indiqué par input_mode.
• duration_seconds est une durée cible, pas une durée à laquelle la vidéo est étirée : la vidéo se termine avec sa narration, qui dure au moins 25 secondes (pour un explainer, uniquement le temps de sa narration) et généralement au plus un quart de plus que duration_seconds, sans dépasser 90 secondes ; une narration plus longue va jusqu’à sa fin. Une vidéo qui dépasse la durée choisie de plus de 5 secondes le signale dans warnings[]. Le montant facturé ne dépasse jamais le devis.
• Les sous-titres omettent la ponctuation, conservent les accents et autres signes diacritiques, et affichent les nombres tels qu’ils sont écrits. Lorsque les sous-titres sont activés, le script est vérifié par rapport à la police des sous-titres avant la création de la voix ; si la police ne peut pas représenter un caractère, l’exécution échoue sans frais.
• La langue de la narration est détectée automatiquement.
• voice indique la voix de narration : choisissez un nom dans GET /v1/voices?skill=make_faceless. Sans ce paramètre, la narration est lue par narrator_en_wise_lady, et un explainer en anglais par la voix la plus rapide. Choisissez une voix dans la langue de la narration. Un nom inconnu, une voix make_ugc et voice_id sont refusés avant toute facturation : make_faceless utilise uniquement les voix qui lui sont répertoriées.
• make_faceless livre toujours une vidéo en 1080p au format 9:16. Lorsque la génération faceless est désactivée sur le serveur, ses deux appels renvoient paid_render_disabled et rien n’est facturé.
• Une exécution échouée dont l’erreur commence par story_not_planned s’est arrêtée à sa première étape : la narration n’a pas pu être planifiée lors de cette tentative. Rien n’a été facturé, et la même entrée peut être relancée avec une nouvelle Idempotency-Key.

Pour make_ugc et create_actor, le format de sortie dépend de la requête et de la source. Les formats pris en charge sont 9:16, 1:1, 16:9 et les résolutions 720p, 1080p ; par défaut, la sortie est en 1080p au format 9:16.

08

Workflows

GET /v1/public/workflows répertorie les méthodes exécutables. Les méthodes natives sont ugc-product-intro, ugc-faq-answer, faceless-explainer et product-image-story. website-proof-demo et kinetic-launch ne peuvent pas encore être exécutées et restent execution_blocked, avec leurs raisons.

Le chemin le plus court avec la CLI commence par l’exemple propre à une méthode. Seul plan-run dépense des crédits ; toutes les commandes précédentes sont gratuites. Modifiez le brief avant de créer le plan et conservez les épingles de méthode.

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

Remplacez wfp_example par le plan_id de plan.json et run_example par l’identifiant d’exécution affiché par plan-run. Un devis expire cinq minutes après son émission ; exécutez donc plan-run peu après plan-quote. Pour product-image-story, téléversez chaque photo avec clipwright upload --json. La réponse fournit son upload_id et son content_digest ; copiez-les directement dans l’asset. Ajoutez un asset par photo. La commande uploads renvoie la même identité pour un téléversement déjà effectué.

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• Créez un plan appartenant au compte, enregistrez des révisions et approuvez la révision exacte et le content_digest. La planification et l’approbation ne coûtent rien et ne lancent aucun rendu. Une révision modifiée nécessite une nouvelle approbation.
• Pour un plan approuvé, envoyez un POST avec un corps vide à /v1/workflow-plans/{id}/quote. Utilisez son quote_id, sa revision, son content_digest et son semantic_input_digest dans la requête d’exécution. Vérifiez expires_at avant de lancer un nouvel achat ; il s’agit de métadonnées du devis. Idempotency-Key doit être identique à idempotency_key dans le corps.
• Les devis de workflow UGC indiquent dans native_quote.quote.warnings que duration_estimate_sec et credits_estimate sont des estimations, et non un prix fixe. Les vidéos UGC courtes livrées sont facturées selon leurs price_lines, sur la vidéo mesurée, chaque durée étant arrondie à la seconde supérieure ; une vidéo plus longue que prévu coûte donc plus cher que l’estimation. Consultez credits_charged sur l’exécution terminée. Un devis natif avec long_form_pricing utilise plutôt les intervalles de présence vérifiés dans la vidéo livrée et le tarif figé à l’admission, et non la durée totale de la vidéo. Les conditions natives en cas d’échec s’appliquent toujours.
• Le tarif natif et les règles en cas d’échec s’appliquent toujours. Faceless duration_seconds sélectionne la durée dont le devis plafonne les frais ; la narration mesurée détermine la durée livrée. La voix, les sous-titres et le script exact accepté conservent leurs paramètres natifs.
• Associez chaque image fournie à un instance_id distinct, un asset_id de téléversement stable et détenu, un content_digest, des droits, une provenance, un usage et une plage de mots sans chevauchement ou une citation sans ambiguïté. Réutilisez un même téléversement dans plusieurs instances ; les URL signées temporaires sont résolues au moment du devis et du lancement.
• Les preuves originales du produit occupent les plans IMAGE pris en charge. L’ouverture générée est illustrative. Un diaporama exact composé uniquement d’images fixes, une ouverture réservée au client et des mises en page de scènes arbitraires ne sont pas disponibles lorsqu’ils sont requis.
• Un protected_area est un rectangle exprimé en fractions de la source. Le précontrôle doit le préserver lors du recadrage, du mouvement PAN et de l’ajout de sous-titres. Toute orientation ou tout placement d’image non vérifié est refusé ; une image générée ne remplace jamais une preuve originale requise.
• Les PNG protégés comportant une animation ou des blocs EXIF, ainsi que les JPEG comportant un segment APP1 (EXIF/XMP), sont refusés. Exportez une copie statique à l’endroit, sans ces métadonnées. La couverture utilise l’horloge native mesurée à 25 fps.
• La durée de conservation des téléversements et la validité de 24 heures de l’URL signée sont des limites indépendantes ; un devis ne prolonge ni l’une ni l’autre. Les sources et les signatures doivent rester disponibles pour le rendu et la récupération. Une nouvelle tentative acceptée conserve ses sources et signatures d’origine.
• Un lancement réussi renvoie le reçu et son Run natif existant. Réessayez la même requête acceptée pour récupérer cet achat, même après l’expiration du devis ou si la signature de la source n’est plus disponible. Consultez la progression et la vidéo livrée avec GET /v1/runs/{id}.
• Les plans privés appartiennent au compte associé au jeton.
• Pour product-image-story, les scènes générées et l’image d’ouverture utilisent les deux premières images originales distinctes admissibles de product_proof, dans l’ordre des ressources acceptées. La première sert d’ancrage à la forme du produit ; la seconde fournit une autre vue. La disponibilité du plan et le devis natif indiquent le nombre sélectionné et précisent que les illustrations générées peuvent différer. Les images originales supplémentaires conservent leurs placements d’image exacts. La récupération d’un ancien point de contrôle payé réutilise ses scènes existantes et affiche un avertissement explicite lorsque le conditionnement par le produit original ne peut pas être vérifié. Les révisions et les candidates, y compris celles conservées et les révisions ultérieures, conservent cette limite connue de conditionnement, sans garantir que les anciennes scènes ou leurs placements survivront à la modification.
• Les écritures rejettent les champs inconnus et les documents de plus de 256000 octets JSON. Les lectures acceptent les champs et valeurs d’énumération futurs ; les champs inconnus d’un document lu sont préservés, afin qu’un client plus ancien refuse une sauvegarde non prise en charge au lieu d’effacer l’intention. Conservez la narration brute acceptée sans la modifier.
• Après la perte de la réponse d’une sauvegarde, répétez la même requête explicite base_version/document. Si le document est déjà devenu le document actuel, le backend renvoie cette révision sans réinitialiser l’approbation ; si un autre document est actuel, il renvoie workflow_conflict. Le SDK, MCP et la CLI n’approuvent, ne génèrent de devis et n’achètent jamais comme effet secondaire d’une sauvegarde.
• GET /v1/runs/{id} peut inclure workflow : son reçu immuable, approved_plan, l’état et les avertissements natifs, actual_output, asset_placements, les advisory beat_dispositions, validation_issues et creative_acceptance=not_reviewed. approved_plan omet brief.reference_profile, afin qu’une interrogation ne le répète pas ; ce que le plan ne reprend pas de la référence figure dans les avertissements, et GET /v1/workflow-plans/{id} renvoie la révision actuelle complète. L’exécution conserve la révision achetée même après la modification du brouillon. Une révision ou une candidate de plan ne récupère jamais le reçu de son ancêtre.
• Le règlement faceless vérifié fournit le condensat de l’artefact, le format et la durée mesurée, même si des données géométriques facultatives sont ensuite manquantes. Les placements nécessitent un point de contrôle intact, lié au compte, à l’exécution et à la requête ; une preuve manquante est indiquée par null avec un problème de validation. Une liste de placements vide vérifiée est []. La livraison UGC vérifiée fournit le format, la durée et le condensat mesurés du fichier final ; le format est déterminé à partir des dimensions mesurées, et non de la requête. Pour les exécutions UGC sans preuve des octets ou du format, y compris les anciennes exécutions, actual_output=null avec output_evidence_unavailable ; leur video_url native reste le résultat. Les preuves historiques ne renouvellent pas une URL de téléchargement expirée et ne prouvent pas l’acceptation créative humaine.
• Les méthodes du SDK sont listWorkflows, getWorkflow, createWorkflowPlan, planReferenceRemake, getWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, quoteWorkflowPlan et runWorkflowPlan ; getRun préserve les preuves du workflow. Les commandes de la CLI sont workflows, workflow-show, plan-create --file, plan-show, plan-save --file, plan-approve --file, plan-quote et plan-run --file. Ces commandes de workflow affichent du JSON ; les fichiers sont limités à 1 MiB avant l’analyse. Un fichier plan-show peut être modifié puis transmis à plan-save pour le même plan.

Exemple de corps pour POST /v1/workflow-plans/{id}/run : remplacez les champs du devis par ceux du devis du plan approuvé et envoyez Idempotency-Key: workflow-example:1.

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

09

Lancer une exécution

Un appel payant comporte un seul en-tête en plus de la clé : Idempotency-Key. POST /v1/skills/make_faceless/run, POST /v1/runs/{id}/revisions, POST /v1/runs/{id}/candidates, POST /v1/skills/make_ugc/run, POST /v1/skills/create_actor/run, POST /v1/workflow-plans/{id}/run, POST /v1/skills/generate_image/run, POST /v1/skills/generate_video/run, POST /v1/reference-analyses, POST /v1/creator-profiles et POST /v1/trend-searches l’exigent ; un appel sans cet en-tête est refusé avec 400 idempotency_key_required avant tout prélèvement.

• Vous choisissez la clé ; c’est le seul élément qui permet de distinguer une nouvelle tentative d’une deuxième commande. N’importe quelle chaîne unique convient ; conservez-la aussi longtemps que vous pourriez renvoyer l’appel.
• La même clé avec le même corps renvoie l’exécution déjà lancée et ne prélève rien une deuxième fois. C’est ce qui rend une nouvelle tentative ordinaire sûre.
• La même clé avec un corps différent est refusée avec 409 idempotency_key_reused. Utilisez une nouvelle clé pour une nouvelle requête au lieu de modifier une requête associée à une clé déjà utilisée.
• Pour lancer délibérément une nouvelle exécution avec la même entrée — une nouvelle tentative après un échec — envoyez une nouvelle clé. L’exécution déjà payée reste inchangée.
• @clipwright/sdk et @clipwright/mcp-server génèrent la clé pour vous à partir du client et de l’entrée, et transforment attempt=2, 3 … en une nouvelle clé. En HTTP brut, c’est à vous de choisir la clé.

10

En cas d’échec d’un appel

Chaque refus contient un objet d’erreur avec un code et un message. La marche à suivre dépend du type de refus, et non du texte :

Refus	HTTP	Répéter le même appel ?	Marche à suivre	Facturé
rate_limited	429	oui, après le délai d’attente	Il s’agit d’une limitation de débit, pas d’une erreur : la réponse indique le nombre de secondes à attendre, dans Retry-After et dans le corps.	Rien. L’appel n’a pas été pris en compte.
server_error	500, 502, 503	oui, après le délai d’attente	L’échec vient du serveur. Ne lancez pas une deuxième exécution avec une nouvelle clé d’idempotence : le même appel constitue la nouvelle tentative.	Pas par cette réponse. Une exécution que le serveur n’a pas pu lancer récupère son crédit réservé ; une exécution effectivement lancée est facturée une seule fois, selon son propre résultat.
insufficient_credits	402	non, la réponse sera identique	Arrêtez-vous et indiquez à la personne le solde et le prix ; les deux figurent dans le corps. Répéter l’appel ne changera ni l’un ni l’autre.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
debt_outstanding	402	non, la réponse sera identique	Arrêtez-vous. L’achat de crédits règle la dette avant que quoi que ce soit ne soit ajouté au solde, ce qui lève le blocage.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
not_admitted	403	non, la réponse sera identique	Arrêtez-vous. Le compte n’a pas accès à la bêta ; ni une nouvelle tentative ni un achat n’y changeront quoi que ce soit. Contactez l’assistance.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
edit_conflict	409	non, la réponse sera identique	Arrêtez-vous. Le brouillon de la modification est à une version différente de celle sur laquelle la sauvegarde devait s’appliquer ; le corps indique laquelle. Consultez le brouillon : s’il contient déjà votre document, une sauvegarde précédente a abouti. Sinon, appliquez la modification au document consulté et sauvegardez avec sa version.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
run_not_editable	409	non, la réponse sera identique	Arrêtez-vous. L’exécution ne comporte aucun brouillon de modification à consulter ou à sauvegarder. Le corps indique l’état et la raison, identiques à ceux affichés dans les shots de l’exécution.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
editing_closed	503	non, la réponse sera identique	Arrêtez-vous. Les modifications payantes ne sont pas ouvertes ; le corps en indique la raison. Rien n’a été facturé et aucune exécution n’a été créée ; paid_edits dans les shots de l’exécution indique quand elles seront ouvertes.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
edit_ceiling_reached	409	non, la réponse sera identique	Arrêtez-vous. L’original a atteint le nombre maximal de révisions ou de candidates de plan (comptées séparément), en cours d’exécution ou en échec et non terminées ; le corps indique la limite, le nombre et les exécutions concernées. Suivez une exécution en cours avec GET /v1/runs/{id} et lancez la suivante une fois celle-ci terminée ; l’assistance augmente la limite d’échecs des révisions après un échec qui nous est imputable.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
edit_invalid	422	non, la réponse sera identique	Arrêtez-vous. Le document ou l’opération demandée par une candidate de plan enfreint les règles de l’exécution modifiée ; issues répertorie chaque problème dans l’ordre. Corrigez la requête : les règles figurent dans les shots de l’exécution.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
workflow_invalid	400	non, la réponse sera identique	Arrêtez-vous. Lisez tous les problèmes et avertissements, puis corrigez le document du workflow. L’approbation, le devis et le lancement payant sont des appels explicites distincts.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
workflow_conflict	409	non, la réponse sera identique	Arrêtez-vous. Consultez le plan enregistré et comparez sa révision et son document à votre requête d’origine. Pour récupérer un lancement dont le résultat est incertain, utilisez la requête et la clé d’idempotence d’origine ; une nouvelle clé peut entraîner un double paiement.	Rien pour cet appel. Un lancement antérieur qui a abouti est facturé une seule fois, selon son propre résultat ; la requête et la clé d’origine le renvoient.
workflow_not_ready	409	non, la réponse sera identique	Arrêtez-vous. Lisez tous les problèmes et avertissements. Résolvez les problèmes de disponibilité, puis approuvez et demandez explicitement un devis pour la révision choisie avant un lancement payant avec clé.	Rien. L’appel a été refusé avant la création d’une exécution ou la réservation de crédits.
client_error	400, 401, 403, 404, 409, 410, 413, 415, 422, 503	non, la réponse sera identique	Arrêtez-vous. La requête elle-même a été refusée : lisez le message, corrigez l’appel, puis renvoyez-le.	Rien pour cet appel : il n’a créé aucune exécution et n’a réservé aucun crédit. Une exécution lancée précédemment avec le même Idempotency-Key (409 idempotency_key_reused) est facturée une seule fois, selon son propre résultat.
Voici tous les codes que l’API place dans error.code. Un code que vous n’avez encore jamais vu suit tout de même la ligne correspondante ci-dessus, car c’est le statut qui détermine la ligne :

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• feedback_limited
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• no_changes
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

11

Limites

• 60 requêtes payantes et 300 requêtes gratuites toutes les 60 secondes. La fenêtre est calculée par compte, et non par clé : des clés supplémentaires n’augmentent donc pas le débit.
• 3 vidéos avec présentateur et 2 vidéos sans visage sont produites simultanément par compte ; les autres sont mises en file d’attente et ne sont pas refusées. Lorsque de nombreux comptes effectuent un rendu en même temps, une exécution peut également attendre son tour derrière les leurs.
• Un refus dû à la limitation du débit indique le nombre de secondes à attendre dans Retry-After et dans le corps de la réponse. Respectez la valeur la plus élevée des deux.
• 99 inserts par clip, et au maximum 16 apparitions de l’acteur entre eux. Les deux valeurs sont calculées à partir des index de mots que vous envoyez ; une demande qui dépasse ces limites est donc refusée avant toute facturation.
• cover_words indique le nombre de mots prononcés couverts par un insert, à partir du premier mot de son ancre. L’insert se termine au début du premier mot non couvert : deux inserts dont les couvertures se rejoignent sont donc adjacents et ne laissent aucun plan de l’acteur entre eux.
• La proportion de mots que vous laissez sans couverture détermine la proportion du clip où un visage apparaît, et ne varie pas en fonction de la vitesse de la voix. La longueur des mots varie toutefois : pour un script de 560 mots, une demande de 19 % donne environ 16 à 22 ; pour un script plus court, la dispersion est plus importante, et une voix différente modifie aussi le résultat.
• Deux choix portant sur un seul mot modifient le prix, et pas seulement l’apparence. Un insert ancré au mot 0 inclut le silence avant le premier mot ; ancré au mot 1, il laisse une apparition supplémentaire de l’acteur, et chaque apparition augmente le prix. De même, une couverture qui atteint le dernier mot prolonge le clip jusqu’à sa fin et supprime l’apparition de clôture.
• Un devis indique la proportion dans estimatedFaceWordShare. Consultez ce champ ; ne divisez pas estimatedFaceSeconds par estimatedTotalDurationSec. Ces deux valeurs répondent à des questions différentes : la première correspond à la réserve que nous retenons à l’extrémité lente de la plage de débit de parole, la seconde indique la durée prévue du clip ; leur rapport ne représente la proportion d’aucun élément.

12

Ce que cette API ne fera jamais

• Publier quoi que ce soit. Nous renvoyons un fichier et un lien signé ; c’est à vous de décider où les envoyer.
• Annuler une exécution démarrée. Aucun endpoint ne le permet.
• Accepter les champs make_ugc suivants : character, broll_url, disclosure_overlay, webhook_url. Ils sont refusés par leur nom avant toute facturation ; ils ne sont ni acceptés ni ignorés discrètement.
• Modifier le format ou la résolution demandés sans vous le signaler. Une incompatibilité entraîne soit un ajustement accompagné d’un avertissement, soit un refus avant l’appel payant.
• Vous rappeler. Il n’y a pas de webhooks : consultez l’exécution avec GET /v1/runs/{id}.
• Afficher une clé une deuxième fois, ni en récupérer une à partir d’une sauvegarde.

13

Autres points à connaître

• Des avertissements, pas de silence. Tout ce que nous n’avons pas pu respecter est indiqué par son nom dans warnings[] sur la même exécution. Aucun paramètre ne disparaît sans explication.
• Un serveur MCP. @clipwright/mcp-server expose le même contrat sous forme d’outils, et tools/list en fournit la version lisible par machine.