Clipwright

API Clipwright

Une API HTTP qui transforme un script en vidéo UGC synchronisée labiale. 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 est également un fichier markdown à https://clipwright.io/docs.md, et un court contrat pour les agents à https://clipwright.io/llms.txt.

Authentification

Chaque appel va à https://api.clipwright.io et porte la clé dans un seul en-tête :

Authorization: Bearer cw_your_key_here

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

03

Ce que ça coûte

• make_ugc à partir d'un script simple : 30 crédits pour chaque seconde de vidéo terminée, arrondis à la seconde entière supérieure.
• make_ugc avec segments ou insertions : 10 crédits pour chaque seconde où un visage est à l'écran, et au moins 400 crédits pour une vidéo livrée. Les secondes sans visage ne coûtent rien, et une exécution qui ne livre aucun fichier ne coûte rien du tout, même si le fournisseur a déjà été payé. Le temps de visage est additionné sur toute la vidéo et arrondi une seule fois, pas par segment. Ces champs nécessitent une qualification longue sur le déploiement ; là où elle est désactivée, ils sont refusés par leur nom avant toute facturation.
• create_actor en qualité medium : 10 crédits pour le portrait et 10 pour chaque format supplémentaire.
• create_actor en qualité high : 20 crédits pour le portrait et 20 pour chaque format supplémentaire.
• Les crédits s'achètent par lots : 1000 crédits pour 10,00 $, un seul paiement, sans abonnement.

Demandez avant de dépenser : le point de terminaison de devis de chaque compétence ne coûte rien. La valeur de sa réponse diffère selon la compétence.

• make_ugc : le devis est une estimation lue à partir des mots du script. La facturation suit ce qui a été mesuré dans la vidéo terminée — sa durée au compteur de script simple, ses secondes de visage au compteur de visage — donc la facture peut être supérieure ou inférieure au devis.
• create_actor : le devis tarifie chaque format demandé, ce qui est le maximum que vous pouvez payer. Vous êtes facturé pour le portrait et pour les variantes réellement publiées ; un format qui n'est pas sorti est nommé dans warnings[] et ne coûte rien.

Ce que coûte une exécution échouée diffère aussi selon la compétence :

• make_ugc à partir d'un script simple : une exécution qui a échoué après que le travail de livraison a atteint le fournisseur est facturée. Celle qui a échoué avant ne coûte rien, tout comme celle que nous avons arrêtée, perdue ou refusée nous-mêmes, même si le fournisseur a déjà été payé. Au compteur de visage, aucun échec n'est facturé.
• create_actor : une exécution échouée ne coûte rien du tout, même si le fournisseur a déjà été payé, car aucun acteur ne vous est parvenu.

04

Points de terminaison

Point de terminaison	Coûte des crédits	Ce qu'il fait
GET /health	non	Vivacité de l'API elle-même. Répond sans clé.
GET /v1/voices	non	Voix que vous pouvez nommer dans voice ou voice_id.
GET /v1/account	non	Solde, dettes et retenues du compte derrière la clé.
POST /v1/skills/make_ugc/quote	non	Tarife un appel make_ugc avec cette entrée. Ne facture rien.
GET /v1/runs/{id}	non	État d'une exécution de n'importe quelle compétence, ses avertissements et son url vidéo.
POST /v1/skills/make_ugc/run	oui	Démarre une exécution vidéo et répond immédiatement avec un run_id. Interrogez l'exécution pour le résultat.
GET /v1/public/skills	non	Catalogue des compétences et de leurs entrées, sans clé.
GET /v1/actors	non	Acteurs enregistrés sur le compte, avec l'id que make_ugc accepte.
DELETE /v1/actors/{id}	non	Oublie un acteur enregistré. Un acteur utilisé par une exécution en cours est conservé.
GET /v1/actors/{id}/defaults	non	Lit la politique par défaut de l'acteur enregistré pour les personnes dans les insertions.
POST /v1/actors/{id}/defaults	non	Définit la politique par défaut de l'acteur enregistré pour les personnes dans les insertions. Une exécution peut la remplacer.
POST /v1/skills/create_actor/quote	non	Tarife un appel create_actor avec cette entrée. Ne facture rien.
POST /v1/skills/create_actor/run	oui	Démarre une exécution d'acteur et répond immédiatement avec un run_id. Interrogez l'exécution pour le résultat.
POST /v1/uploads	non	Prend des octets d'image et renvoie l'url https que make_ugc et create_actor acceptent.

Une exécution de l'une ou l'autre compétence est relue au même endroit, GET /v1/runs/{id}, et passe par ces états : queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

05

Compétences et leurs entrées

make_ugc. Démarrez la génération d'une vidéo UGC synchronisée labiale. Donnez un script dans la limite de texte du modèle de parole sélectionné ; l'acteur vient de actor_id (un acteur enregistré de list_actors) ou image, sinon l'acteur par défaut est utilisé. Le format et la résolution suivent la requête et la source, avec 1080x1920 par défaut. Les sous-titres sont OPT-IN : demandez d'abord à l'utilisateur. Les champs que le rendu n'honore pas encore portent une note NOT HONORED YET dans leur propre description — lisez-la au lieu de deviner.

Appelez quote_ugc avant de générer et affichez le coût. Cela n'attend PAS la vidéo : cela démarre l'exécution et renvoie un run_id IMMÉDIATEMENT. Vous DEVEZ ensuite interroger get_run avec ce run_id jusqu'à ce que l'état soit 'succeeded' (video_url) ou 'failed'. Une exécution 'failed' dont nous détenons encore le travail payé du fournisseur peut revenir à 'queued' et atteindre 'succeeded' plus tard ; chaque fois que cela arrive, elle est nommée dans warnings[]. Passez attempt=2,3,… pour démarrer délibérément une NOUVELLE exécution pour la même entrée (nouvelle tentative après un échec).

Champ	Requis	Ce que ça signifie
script	facultatif	Les mots que l'acteur prononce ; requis sauf si segments fournit le texte parlé. Les segments et les insertions ancrées au texte nécessitent une qualification longue sur le serveur. Limites de script par modèle de parole : eleven_v3 : 5000 caractères ; eleven_flash_v2_5 : 10000 caractères ; eleven_turbo_v2_5 : 10000 caractères. Le compte inclut les espaces, les balises audio et les marques d'accent ; les emoji peuvent compter pour deux caractères. Il n'y a pas de limite de nombre de mots. La durée et le prix sont des estimations jusqu'à mesure. Accent russe : écrivez la voyelle accentuée en majuscule dans un mot en minuscules ("потОм", "зАмок") et eleven_v3 la reçoit comme marque d'accent U+0301 ("пото́м") ; une marque tapée directement est conservée. Une majuscule en début de mot reste une majuscule, et un mot avec une deuxième majuscule ou une consonne majuscule à l'intérieur (tout en majuscules, "ВУЗы") est laissé tel quel. Une seule voyelle majuscule dans un mot est toujours lue comme un accent, donc écrivez "Яндекс Еда", pas "ЯндексЕда". Dites aux utilisateurs écrivant en russe qu'ils peuvent marquer l'accent de cette façon. eleven_flash_v2_5 et eleven_turbo_v2_5 coûtent moins cher mais lisent mal les marques d'accent : les majuscules leur parviennent inchangées.
segments	facultatif	Segments ordonnés d'acteur et d'image ; nécessite une qualification longue sur le serveur, captions=false et 1080p. Les médias image nécessitent broll_policy=anyone explicite.
inserts	facultatif	Insertions d'images ancrées au texte sur la narration complète, chacune couvrant cover_words mots parlés depuis son ancre ; nécessite une qualification longue sur le serveur, captions=false, 1080p et broll_policy=anyone explicite.
person	facultatif	NOT HONORED YET : person n'est pas encore honoré : cette requête utilise l'acteur par défaut ; choisissez actor_id dans list_actors ou fournissez image pour sélectionner un autre visage
actor_id	facultatif	ID d'acteur Clipwright enregistré de list_actors. Choisissez actor_id, image ou person ; ne les combinez pas. Sans voice ni voice_id, la voix suit le genre de l'acteur. Ne combinez pas avec actor_gender.
image	facultatif	Url https publique de la photo de l'acteur (PNG, JPEG ou WebP, jusqu'à 10 Mo). Un fichier sur disque passe d'abord par upload_image (POST /v1/uploads) — passez l'url qu'il renvoie. Une source que nous ne pouvons pas utiliser — hôte privé ou loopback, http, inaccessible, redirigeant, plus de 10 Mo, ou pas un de ces types d'image — est refusée (unusable_source) avant toute facturation. Nous ne détectons pas le genre du visage : passez 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 : choisit la voix par défaut de ce genre (female : sarah, male : george). Refusé avec actor_id (son genre est connu) et sans image. Une voice ou voice_id explicite l'emporte et la réponse avertit que actor_gender n'a rien changé.
name	facultatif	NOT HONORED YET : name n'est pas encore honoré : il n'atteint pas le rendu
broll_policy	facultatif	STORED ONLY : Politique enregistrée pour le B-roll : anyone autorise les personnes y compris l'acteur ; no_actor exclut l'acteur ; no_people exclut toutes les personnes, y compris les mains. La génération de médias segmentés est fermée. Ce paramètre est uniquement stocké et n'a aucun effet sur les vidéos d'acteur seul. Le remplacement d'exécution l'emporte sur la valeur par défaut de l'acteur du compte ; sinon no_people.
captions	facultatif	NOT HONORED YET : sous-titres demandés mais non rendus dans ce prototype (stage-B)
caption_style	facultatif	NOT HONORED YET : caption_style n'est pas honoré : les sous-titres ne sont pas rendus dans ce prototype (stage-B)
look	facultatif	NOT HONORED YET : look n'est pas encore honoré : il n'atteint pas le rendu
aspect_ratio	facultatif	Format de sortie : 9:16 | 1:1 | 16:9. Omis signifie 9:16, et une source d'une autre forme est ajustée à 9:16 avec un avertissement — passez-le explicitement chaque fois que vous passez image. Un écart supérieur à 15 % entre la requête et la source est refusé (aspect_conflict) avant toute facturation.
resolution	facultatif	Résolution de sortie : 720p | 1080p | 4k (petit côté 720 / 1080 / 2160 px). Omis signifie 1080p.
voice	facultatif	Nom de voix de list_voices. Préréglages organisés : owner_ru_clone | sarah | george | eric | daria_ru_female (owner_ru_clone est la voix russe clonée). L'API refuse un nom que list_voices ne renvoie pas, avant toute facturation. Omis signifie la voix par défaut pour le genre de l'acteur : le genre de actor_id, actor_gender avec image, ou george pour l'acteur par défaut et pour image sans actor_gender. Mutuellement exclusif avec voice_id.
voice_id	facultatif	Id de voix brute du fournisseur (16–32 lettres et chiffres) pour une voix hors catalogue. Vérifié paresseusement : un id inconnu fait échouer l'exécution, pas la requête. Mutuellement exclusif avec voice.
tts_model	facultatif	Modèle de parole : eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5. Omis signifie le modèle du préréglage choisi (list_voices le montre ; chaque préréglage parle eleven_v3) ou eleven_v3 pour un voice_id brut. eleven_v3 est le plus expressif et le seul qui lit les marques d'accent (une voyelle majuscule dans un mot russe, "потОм", devient une ; voir script) ; eleven_flash_v2_5 et eleven_turbo_v2_5 sont des alternatives moins chères pour les langues autres que le russe. Limites de script par modèle de parole : eleven_v3 : 5000 caractères ; eleven_flash_v2_5 : 10000 caractères ; eleven_turbo_v2_5 : 10000 caractères. Le compte inclut les espaces, les balises audio et les marques d'accent ; les emoji peuvent compter pour deux caractères. Il n'y a pas de limite de nombre de mots. La durée et le prix sont des estimations jusqu'à mesure.
disclosure_overlay	facultatif	Valeurs acceptées : true | false.
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 9:16 avec exactement un visage, plus les autres formats demandés édités à partir de celui-ci. Renvoie un run_id immédiatement ; interrogez get_run jusqu'à 'succeeded' (created_actor.actor_id, puis passez-le comme actor_id à make_ugc) ou 'failed'. Chaque image publiée est facturée au prix que le devis montre ; 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.

Champ	Requis	Ce que cela signifie
description	requis	Mots décrivant un adulte fictif : apparence, vêtements, décor. Nommer une personne réelle ou une ressemblance avec une personne réelle est refusé avant toute facturation (actor_prompt_refused).
gender	requis	female | male. Fixe le genre de l'acteur et la voix par défaut des vidéos avec cet acteur.
approximate_age	requis	Âge approximatif en années, de 18 à 90 : les acteurs sont des adultes.
name	requis	Nom affiché dans list_actors.
aspect_ratios	facultatif	Formats à créer : 9:16 | 1:1 | 16:9, incluant toujours 9:16. Omis signifie les trois. Les formats qui échouent à la vérification d'identité ne sont pas facturés et sont nommés dans les avertissements.
quality	facultatif	Qualité d'image : medium | high. Omis signifie medium. Le prix par image en dépend ; le devis le montre avant toute facturation.

Le format de sortie suit la demande et la source. Les formats pris en charge sont 9:16, 1:1, 16:9 et les résolutions 720p, 1080p, 4k ; le silence signifie 1080p en 9:16.

06

Démarrage d'une exécution

Un appel payant comporte un en-tête en plus de la clé : Idempotency-Key. POST /v1/skills/make_ugc/run et POST /v1/skills/create_actor/run l'exigent, et un appel sans celui-ci est refusé avec 400 idempotency_key_required avant toute facturation.

• Vous choisissez la clé, et c'est la seule chose qui distingue une nouvelle tentative d'une seconde commande. Toute chaîne unique convient ; conservez-la tant que vous pourriez renvoyer l'appel.
• La même clé avec le même corps renvoie l'exécution déjà démarrée et ne facture rien une seconde 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. Prenez une nouvelle clé pour une nouvelle demande au lieu de modifier une demande sous une clé déjà utilisée.
• Pour démarrer délibérément une nouvelle exécution sur la même entrée — une nouvelle tentative après un échec — envoyez une nouvelle clé. L'exécution déjà payée reste où elle est.
• @clipwright/sdk et @clipwright/mcp-server construisent la clé pour vous à partir du client et de l'entrée, et transforment attempt=2, 3 … en une nouvelle clé. Sur HTTP simple, la clé est à vous de choisir.

07

Quand un appel échoue

Chaque refus comporte un objet d'erreur avec un code et un message. Ce qu'il faut faire en découle du type de refus, pas du texte :

Refus	HTTP	Répéter le même appel ?	Que faire
rate_limited	429	oui, après l'attente	Pression de retour, pas une erreur : la réponse nomme les secondes à attendre, dans Retry-After et dans le corps.
server_error	500, 502, 503	oui, après l'attente	L'échec est côté serveur. Ne démarrez pas une seconde exécution avec une nouvelle clé d'idempotence : le même appel est la nouvelle tentative.
insufficient_credits	402	non, cela donne la même réponse	Arrêtez-vous et dites à la personne le solde et le prix ; les deux sont dans le corps. Répéter ne peut changer ni l'un ni l'autre.
debt_outstanding	402	non, cela donne la même réponse	Arrêtez-vous. Acheter des crédits efface la dette avant que quoi que ce soit n'atteigne le solde, et cela lève le blocage.
not_admitted	403	non, cela donne la même réponse	Arrêtez-vous. Le compte n'a pas d'accès bêta ; ni une nouvelle tentative ni un achat ne changent cela. Demandez à l'opérateur.
client_error	400, 401, 404, 409, 413, 415	non, cela donne la même réponse	Arrêtez-vous. La demande elle-même a été refusée : lisez le message, corrigez l'appel, puis renvoyez-le.

Ce sont tous les codes que l'API place dans error.code. Un code que vous n'avez jamais vu suit toujours sa ligne ci-dessus, car la ligne est choisie par le statut :

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

Limites

• 60 demandes payantes et 300 gratuites par 60 secondes. La fenêtre est comptée par compte, pas par clé, donc des clés supplémentaires n'achètent pas plus de débit.
• 3 rendus s'exécutent à la fois par compte ; le reste fait la queue et n'est pas refusé.
• Un refus par limite de débit nomme les secondes à attendre dans Retry-After et dans le corps. Honorez la plus grande des deux.
• 49 insertions par clip, et au plus 6 apparitions de l'acteur entre elles. Les deux sont comptés à partir des index de mots que vous envoyez, donc une entrée qui en demande plus est refusée avant que quoi que ce soit soit payé.
• cover_words indique combien de mots parlés une insertion couvre, comptés à partir du premier mot de son ancrage. L'insertion se termine là où le premier mot non couvert commence, donc deux insertions dont les couvertures se rejoignent sont adjacentes et ne laissent aucun plan de l'acteur entre elles.
• La part de mots que vous laissez non couverts décide de la part du clip qui montre un visage, et elle ne bouge pas avec la vitesse de la voix. La longueur des mots varie : avec un script de 560 mots, demander 19 % a donné 16 à 22 dans neuf cent quatre-vingt-dix-sept simulations sur mille, et est resté dans 15 à 24 sur cinquante mille. Ces nombres ont été mesurés sur la voix de ce profil et à cette longueur ; un script plus court disperse plus largement, et une voix différente les déplace.
• Deux choix d'un seul mot changent le prix, pas seulement l'apparence. Une insertion ancrée au mot 0 possède le silence avant le premier mot ; ancrée au mot 1, elle laisse une apparition supplémentaire de l'acteur, et chaque apparition est un travail payant séparé. Une couverture qui atteint le dernier mot amène le clip à sa fin et supprime l'apparition de clôture de la même manière.
• Un devis rapporte la part comme estimatedFaceWordShare. Lisez ce champ ; ne divisez pas estimatedFaceSeconds par estimatedTotalDurationSec. Ces deux répondent à des questions différentes — la première est la réserve que nous tenons à l'extrémité lente de la plage de parole, la seconde est la durée prévue du clip — et leur rapport n'est la part de rien.

09

Ce que cette API ne fera jamais

• Publier quoi que ce soit. Nous renvoyons un fichier et un lien signé ; où il va est à vous de décider.
• Annuler une exécution démarrée. Il n'y a pas de point de terminaison pour cela : une fois que le fournisseur a le travail, l'arrêter de notre côté ne le dépenserait pas.
• Accepter ces champs : character, broll_url, webhook_url. Ils sont refusés par nom avant toute facturation, pas acceptés et ignorés silencieusement.
• Changer le format ou la résolution demandés sans le dire. Une inadéquation est soit corrigée avec un avertissement, soit refusée avant l'appel payant.
• Vous rappeler. Il n'y a pas de webhooks : lisez l'exécution avec GET /v1/runs/{id}.
• Afficher une clé une seconde fois, ou en récupérer une à partir d'une sauvegarde.

10

Aussi bon à savoir

• Des avertissements, pas du silence. Tout ce que nous n'avons pas pu honorer revient dans warnings[] sur la même exécution, nommé. Un paramètre ne disparaît jamais sans une ligne à son sujet.
• Un serveur MCP. @clipwright/mcp-server expose le même contrat sous forme d'outils, et son tools/list est la forme lisible par machine de cette page.