Automatiser vos vidéos avec l'API PageToVid
L'API de génération vidéo de PageToVid transforme une URL en MP4 narré en un seul appel HTTP : vous envoyez la page et un brief à /api/v1/videos avec votre clé, vous recevez aussitôt un identifiant, puis la vidéo, l'affiche et le fichier de sous-titres à la fin du rendu, par interrogation ou via un webhook signé. Elle est incluse à partir de l'offre Pro, et un rendu coûte les mêmes 40 crédits que dans le tableau de bord.
Ce guide s'adresse au développeur à qui l'on demande de donner à chaque nouveau produit, annonce ou version sa propre vidéo, sans que personne n'ouvre un logiciel de montage. Il couvre la requête, le webhook, les champs qui comptent et les erreurs qui rendent un pipeline automatisé coûteux. La référence des points d'accès est sur la page développeurs.
MolForge, « Test the molecule before you make it » : un film 16:9 de 27 secondes pour un outil de découverte de médicaments in silico, cinq scènes et 43 mots, avec une version 9:16 de 29 secondes écrite à part.
Un rendu, du début à la fin
Le rendu est asynchrone : un film prend quelques minutes, l'API s'organise donc autour d'un identifiant que vous revenez chercher.
Créez une clé
Sur la page de votre compte, générez une clé d'API. Elle commence par
cp_live_, elle est liée à votre compte et à votre solde de crédits, et se place dans l'en-têteAuthorization: Bearer cp_live_…. Traitez-la comme un mot de passe : elle peut dépenser des crédits.Lancez le rendu
Envoyez un POST à
/api/v1/videosen JSON :url(une page publique) et, en option,goal(explainer, ad, demo, tutorial, article),targetSeconds(de 15 à 180),aspect(16:9, 9:16, 1:1 ou 4:5),language,focus(votre brief, jusqu'à 2 000 caractères) etcallbackUrl. Ajoutez un en-têteIdempotency-Key.Conservez l'identifiant
La réponse est un 202 avec
id,statusUrlet, la première fois que vous passez un callback, le secret du webhook, affiché une seule fois. Gardez les trois. Rien n'est encore rendu.Attendez la fin
Recevez le webhook, ou interrogez
statusUrlavec un délai croissant. Le statut passe par queued, analyzing, scripting, recording, voicing et rendering, puis s'arrête sur done, held ou error.Lisez le résultat, puis les avertissements
Un rendu terminé renvoie
videoUrl,posterUrl,subtitleUrl(WebVTT),durationMs, largeur et hauteur, unepageUrlpublique et unscorede qualité. SihasWarningsvaut true, lisezwarningsavant de publier.
Les refus ne coûtent rien et disent pourquoi : une page derrière une vérification anti-robot ou qui renvoie une erreur HTTP, une adresse privée, un solde vide (402, NO_CREDITS) ou une offre sans API (402, UPGRADE_REQUIRED). Lisez le code et passez à l'élément suivant ; relancer une page refusée en boucle ne change rien tant que la page ne change pas.
Webhooks : vérifier avant de faire confiance
Quand un rendu atteint done, held, error ou cancelled, nous envoyons un événement JSON à son callbackUrl (ou au webhook par défaut du compte). Chaque événement porte trois en-têtes : X-PageToVid-Timestamp, X-PageToVid-Signature et X-PageToVid-Event-Id.
Votre récepteur doit :
- Recalculer un HMAC-SHA256 avec votre secret sur l'horodatage, un point et le corps brut, puis le comparer en temps constant à la valeur
sha256=. Analysez le JSON après, jamais avant. - Rejeter un horodatage de plus de cinq minutes. C'est un rejeu.
- Dédoublonner sur l'identifiant d'événement : un même événement n'est jamais livré sous deux identifiants, mais il peut arriver plusieurs fois.
- Répondre vite en 2xx et faire le travail de publication ensuite.
La livraison est tentée trois fois, à quelques secondes d'intervalle, et les redirections ne sont pas suivies : pointez le callback directement sur votre récepteur. Si un événement vous a échappé, le point d'accès de statut a toujours la réponse. Nous l'avons conçu ainsi après avoir vu des intégrations interroger pendant quinze minutes ; le webhook supprime la boucle.
L'exemple : MolForge en 27 secondes
MolForge (molforge.ai) prédit les propriétés ADMET de molécules avant que quiconque les synthétise. Le film 16:9 dure 27 secondes, cinq scènes, 43 mots en anglais. Il s'ouvre sur un clip IA d'une chimiste seule au labo, la nuit, sous « Months at the bench. Weeks of assays. » (des mois à la paillasse, des semaines d'essais), enchaîne sur une main gantée qui jette un flacon raté (« Then the molecule fails anyway »), puis une carte de conversation où MolForge rend un profil complet et signale les risques avant toute synthèse. Une carte grand chiffre affiche 92M+ composés à explorer et cribler. Le dernier clip montre une chimiste dans un labo lumineux devant une molécule en 3D : « Fail fast. On screen, not in the lab. »
Ce film est un storyboard écrit, rendu en animation, sans page filmée. Pour l'automatisation, la nuance compte : /api/v1/videos prend une URL et la filme, tandis qu'un storyboard que vous générez vous-même (à partir d'un journal des modifications, d'un jeu de données, d'un flux produit) passe par l'outil create_animation du point d'accès MCP, avec la même clé. Voir créer des vidéos avec Claude via MCP.
La version 9:16 dure 29 secondes et ajoute un temps, « Your best candidate, finally ready », avant l'échec. Nous l'avons écrite comme un second storyboard parce que le vertical avait besoin de cette respiration. Quand le script ne change pas, demandez les deux formats en un seul appel avec outputs.
Les champs qui changent le résultat
La plupart des intégrations n'ont besoin que de url, aspect et callbackUrl. Voici ceux qui valent la peine ensuite.
| Champ | Ce qu'il fait | Quand l'utiliser |
|---|---|---|
| Votre brief : l'offre, le public, les phrases entre guillemets dites mot pour mot | Chaque page produit ou annonce : mettez-y le prix et l'appel à l'action |
| Jusqu'à quatre formats depuis un seul storyboard ; chaque format en plus est un rendu | 16:9 pour la page et 9:16 pour les réseaux, même script |
| Un score minimum et la conduite en dessous : correction auto, mise en attente ou livraison | Tout pipeline qui publie sans regard humain |
| Un aperçu gratuit, filigrané, basse résolution, dans une petite limite horaire | Tester votre intégration avant de dépenser des crédits |
| Comment la voix doit prononcer une marque ou un terme | Les noms de produits que la voix écorche |
En-tête | La même clé renvoie le même rendu ; des paramètres modifiés sont refusés en 409 | Chaque appel de création, toujours |
Deux autres portes avec la même clé : POST /api/v1/videos/:id/translate crée un nouveau film par langue (jusqu'à 6 par appel, narration revoicée et resous-titrée ; voir localiser des vidéos en plusieurs langues), et les points d'accès de site analysent un domaine et proposent les pages qui méritent un film, avec un aperçu gratuit avant tout lancement.
Coûts, limites et les trois erreurs coûteuses
Un rendu coûte 40 crédits, quelle que soit sa durée ; chaque format supplémentaire est un rendu de plus ; les brouillons sont gratuits ; les clips et images IA s'ajoutent et sont chiffrés avant d'être dépensés (voir les crédits et le coût d'une vidéo). Il n'y a pas de prix par appel ; les prix des offres sont sur la page tarifs. Un compte peut lancer dix rendus par minute : un lot de deux cents est une file d'attente, pas une rafale. Envoyez, stockez l'identifiant, laissez revenir les webhooks. Un rendu qui échoue pour une raison technique est remboursé automatiquement.
Les erreurs que nous voyons dans de vraies intégrations :
- Relancer sans Idempotency-Key. Un délai dépassé chez vous ne veut pas dire que le rendu n'a pas démarré. Sans clé, la relance est un second film et un second débit.
- Refaire les rendus sur une tâche planifiée. Une tâche nocturne sur un catalogue qui ne bouge pas paie chaque nuit le même film. Déclenchez sur changement : un nouveau produit, un prix modifié, une nouvelle version.
- Publier sur le seul statut done. Un film terminé peut porter des avertissements : une scène retombée sur une carte, une page lente à charger. Filtrez sur
hasWarningset le score, ou réglezqualityGatesur la mise en attente.
Et classez avant de générer : un film sur une page que personne ne visite, ce sont 40 crédits dépensés pour rien. Commencez par vos pages les plus visitées, comme dans le cas d'usage publicités vidéo e-commerce, mesurez, puis élargissez.
Quand l'API n'est pas le bon outil
Vous faites quelques films par mois. Le tableau de bord ou un assistant va plus vite qu'une intégration : collez l'URL, ou demandez à Claude via le serveur MCP, disponible sur toutes les offres. La configuration MCP prend quelques minutes.
Vous voulez le même film chaque semaine à partir d'un flux. C'est une émission, pas un script à maintenir : un flux, un format et des plafonds, avec un aperçu gratuit. Voir les émissions vidéo récurrentes et le cas d'usage vidéo de notes de version.
Il vous faut quelqu'un à l'écran ou un montage sur mesure. Une API rend ce que la page et le brief lui donnent. Une formation avec présentateur ou un film de marque relèvent d'un studio ou d'un outil d'avatars ; la page de comparaison montre où se placent les autres outils.
Vos pages sont privées. L'API filme des pages publiques. Les écrans derrière une connexion demandent une session de capture, à partir de l'offre Scale.
Transformez votre site en vidéo — gratuitement
Collez la page à filmer. PageToVid écrit le script, filme le vrai site, enregistre la voix et livre le MP4.
Questions fréquentes
Quelle offre inclut l'API de génération vidéo ?
L'offre Pro et toutes celles au-dessus. Les appels ne sont pas facturés à part : chaque rendu consomme les crédits du compte auquel appartient la clé, exactement comme un rendu lancé depuis le tableau de bord.
Dois-je interroger l'API pour obtenir le résultat ?
Non. Passez un callbackUrl et nous envoyons un événement signé quand le rendu est terminé, mis en attente, en échec ou annulé. Interroger l'URL de statut avec un délai croissant fonctionne aussi et sert de solution de repli si un événement s'est perdu.
Peut-on créer une vidéo sans page web ?
Pas avec le point d'accès videos, qui filme une URL. Un storyboard que vous écrivez ou générez se rend en animation via l'outil create_animation du point d'accès MCP, avec la même clé d'API.
Comment éviter qu'une relance soit facturée deux fois ?
Envoyez un en-tête Idempotency-Key à chaque appel de création. La même clé renvoie le rendu existant ; la même clé avec d'autres paramètres est refusée en 409 et rien n'est débité.