Automatizar vídeos con la API de PageToVid
La API de generación de vídeo de PageToVid convierte una URL en un MP4 narrado con una sola llamada HTTP: envías la página y un encargo a /api/v1/videos con tu clave, recibes al instante un identificador y, cuando termina el render, el vídeo, la miniatura y el archivo de subtítulos, consultando el estado o mediante un webhook firmado. Está en el plan Pro y superiores, y un render cuesta los mismos 40 créditos que uno hecho desde el panel.
Esta guía es para el desarrollador al que le han pedido que cada producto, anuncio o versión nueva tenga su propio vídeo sin que nadie abra un editor. Cubre la petición, el webhook, los campos que importan y los errores que encarecen un flujo automatizado. La referencia de los endpoints está en la página para desarrolladores.
MolForge, «Test the molecule before you make it»: un vídeo 16:9 de 27 segundos para una herramienta de descubrimiento de fármacos in silico, cinco escenas y 43 palabras, con una versión 9:16 de 29 segundos escrita aparte.
Un render de principio a fin
El render es asíncrono: un vídeo tarda minutos, así que la API gira en torno a un identificador al que vuelves después.
Crea una clave
En la página de tu cuenta, genera una clave de API. Empieza por
cp_live_, va ligada a tu cuenta y a tu saldo de créditos, y se envía en la cabeceraAuthorization: Bearer cp_live_…. Trátala como una contraseña: puede gastar créditos.Lanza el render
Haz un POST a
/api/v1/videoscon JSON:url(una página pública) y, si quieres,goal(explainer, ad, demo, tutorial, article),targetSeconds(de 15 a 180),aspect(16:9, 9:16, 1:1 o 4:5),language,focus(tu encargo, hasta 2.000 caracteres) ycallbackUrl. Añade una cabeceraIdempotency-Key.Guarda el identificador
La respuesta es un 202 con
id,statusUrly, la primera vez que pasas un callback, el secreto del webhook, que solo se muestra una vez. Guarda los tres. Todavía no se ha renderizado nada.Espera al final
Recibe el webhook o consulta
statusUrlcon esperas crecientes. El estado pasa por queued, analyzing, scripting, recording, voicing y rendering, y se detiene en done, held o error.Lee el resultado y luego los avisos
Un render terminado devuelve
videoUrl,posterUrl,subtitleUrl(WebVTT),durationMs, ancho y alto, unapageUrlpública y una puntuación de calidadscore. SihasWarningses true, leewarningsantes de publicar.
Los rechazos no cuestan nada y dicen por qué: una página tras una comprobación antirrobots o que responde con un error HTTP, una dirección privada, un saldo vacío (402, NO_CREDITS) o un plan sin API (402, UPGRADE_REQUIRED). Lee el code y pasa al siguiente elemento; reintentar en bucle una página rechazada no cambia nada hasta que cambie la página.
Webhooks: verifica antes de fiarte
Cuando un render llega a done, held, error o cancelled, enviamos un evento JSON a su callbackUrl (o al webhook por defecto de la cuenta). Cada evento lleva tres cabeceras: X-PageToVid-Timestamp, X-PageToVid-Signature y X-PageToVid-Event-Id.
Tu receptor debe:
- Recalcular un HMAC-SHA256 con tu secreto sobre la marca de tiempo, un punto y el cuerpo en bruto, y compararlo en tiempo constante con el valor
sha256=. Analiza el JSON después, nunca antes. - Rechazar una marca de tiempo de más de cinco minutos. Eso es una repetición.
- Eliminar duplicados por el identificador del evento: un mismo evento nunca llega con dos identificadores, pero puede llegar más de una vez.
- Responder rápido con un 2xx y hacer la publicación después.
La entrega se intenta tres veces, con pocos segundos de diferencia, y no se siguen redirecciones: apunta el callback directamente a tu receptor. Si se te escapó un evento, el endpoint de estado sigue teniendo la respuesta. Lo diseñamos así después de ver integraciones consultando durante quince minutos; el webhook elimina el bucle.
El ejemplo: MolForge en 27 segundos
MolForge (molforge.ai) predice las propiedades ADMET de las moléculas antes de que nadie las sintetice. El vídeo 16:9 dura 27 segundos, cinco escenas, 43 palabras en inglés. Abre con un clip de IA de una química sola en el laboratorio de noche, con «Months at the bench. Weeks of assays.» (meses en la poyata, semanas de ensayos), pasa a una mano con guante que tira un vial fallido a la papelera («Then the molecule fails anyway»), luego una tarjeta de chat en la que MolForge devuelve un perfil completo y marca los riesgos antes de sintetizar nada. Una tarjeta de cifra grande muestra 92M+ compuestos para buscar y cribar. El último clip es una química en un laboratorio luminoso ante una molécula en 3D: «Fail fast. On screen, not in the lab.»
Este vídeo es un guion gráfico escrito y renderizado como animación, sin página grabada. Para automatizar, el matiz importa: /api/v1/videos recibe una URL y la graba, mientras que un guion gráfico que generas tú (a partir de un registro de cambios, un conjunto de datos, un feed de productos) pasa por la herramienta create_animation del endpoint MCP, con la misma clave. Mira hacer vídeos con Claude por MCP.
La versión 9:16 dura 29 segundos y añade un tiempo, «Your best candidate, finally ready», antes del fracaso. La escribimos como un segundo guion gráfico porque el vertical necesitaba esa pausa. Cuando el guion no cambia, pide los dos formatos en una sola llamada con outputs.
Los campos que cambian el resultado
La mayoría de integraciones solo necesitan url, aspect y callbackUrl. Estos son los que merece la pena añadir después.
| Campo | Qué hace | Cuándo usarlo |
|---|---|---|
| Tu encargo: la oferta, el público, frases entre comillas que se dicen palabra por palabra | Cada página de producto o anuncio: pon aquí el precio y la llamada a la acción |
| Hasta cuatro formatos desde un mismo guion gráfico; cada formato extra es un render | 16:9 para la página y 9:16 para redes, mismo guion |
| Una puntuación mínima y qué hacer por debajo: corregir solo, retener o entregar | Cualquier flujo que publique sin que nadie mire |
| Una vista previa gratis, con marca de agua y baja resolución, dentro de un pequeño cupo por hora | Probar tu integración antes de gastar créditos |
| Cómo debe pronunciar la voz una marca o un término | Nombres de producto que la voz dice mal |
Cabecera | La misma clave devuelve el mismo render; con parámetros distintos se rechaza con 409 | Cada llamada de creación, siempre |
Dos puertas más con la misma clave: POST /api/v1/videos/:id/translate crea un vídeo nuevo por idioma (hasta 6 por llamada, con locución y subtítulos rehechos; mira localizar vídeos a varios idiomas), y los endpoints de sitio analizan un dominio y proponen qué páginas merecen un vídeo, con una vista previa gratuita antes de lanzar nada.
Costes, límites y los tres errores caros
Un render cuesta 40 créditos, dure lo que dure; cada formato extra es otro render; los borradores son gratis; los clips e imágenes de IA se suman y se presupuestan antes de gastarse (mira los créditos y lo que cuesta un vídeo). No hay precio por llamada; los precios de los planes están en precios. Una cuenta puede lanzar diez renders por minuto, así que un lote de doscientos es una cola, no una ráfaga: envía, guarda el identificador y deja que vuelvan los webhooks. Un render que falla por un motivo técnico se reembolsa automáticamente.
Los errores que vemos en integraciones reales:
- Reintentar sin Idempotency-Key. Que se te agote el tiempo de espera no significa que el render no haya empezado. Sin clave, el reintento es un segundo vídeo y un segundo cobro.
- Volver a renderizar con un cron. Una tarea nocturna sobre un catálogo que no cambia paga cada noche el mismo vídeo. Lanza por cambio: un producto nuevo, un precio actualizado, una versión.
- Publicar solo porque pone done. Un vídeo terminado puede traer avisos: una escena que cayó en una tarjeta, una página que cargó lenta. Filtra por
hasWarningsy la puntuación, o configuraqualityGatepara retener.
Y ordena antes de generar: un vídeo en una página que nadie visita son 40 créditos gastados en nada. Empieza por tus páginas con más tráfico, como en el caso de uso de anuncios en vídeo para e-commerce, mide y luego amplía.
Cuándo la API no es la herramienta adecuada
Haces pocos vídeos al mes. El panel o un asistente son más rápidos que escribir una integración: pega la URL o pídeselo a Claude a través del servidor MCP, que funciona en todos los planes. La configuración MCP lleva unos minutos.
Quieres el mismo vídeo cada semana a partir de un feed. Eso es un programa, no un script que mantener: un feed, un formato y unos topes, con vista previa gratuita. Mira programas de vídeo recurrentes y el caso de uso de vídeo de notas de versión.
Necesitas a una persona en cámara o un montaje a medida. Una API renderiza lo que le dan la página y el encargo. Un curso con presentador o una pieza de marca son trabajo de un estudio o de una herramienta de avatares; la página de comparación muestra dónde encaja cada herramienta.
Tus páginas son privadas. La API graba páginas públicas. Las pantallas tras un inicio de sesión necesitan una sesión de captura, desde el plan Scale.
Convierte tu sitio web en un vídeo — gratis
Pega la página que quieres filmar. PageToVid escribe el guion, graba el sitio real, pone la voz y entrega el MP4.
Preguntas frecuentes
¿Qué plan incluye la API de generación de vídeo?
El plan Pro y todos los superiores. Las llamadas no se cobran aparte: cada render gasta créditos de la cuenta a la que pertenece la clave, igual que un render hecho desde el panel.
¿Tengo que consultar el estado para obtener el resultado?
No. Pasa un callbackUrl y te enviamos un evento firmado cuando el render termina, queda retenido, falla o se cancela. Consultar la URL de estado con esperas crecientes también funciona y es el plan B si se perdió un evento.
¿Puedo crear un vídeo sin página web?
No con el endpoint de vídeos, que graba una URL. Un guion gráfico que escribas o generes se renderiza como animación con la herramienta create_animation del endpoint MCP, usando la misma clave de API.
¿Cómo evito que un reintento me cobre dos veces?
Envía una cabecera Idempotency-Key en cada llamada de creación. La misma clave devuelve el render existente; la misma clave con otros parámetros se rechaza con un 409 y no se cobra nada.