Intervalo
"every": 2Un fotograma cada N segundos (0,1–3600). Ideal para datasets, miniaturas y revisión de escenas.
API de GetVideoFrames
Una petición convierte un enlace de video en fotogramas.
Envía una URL de YouTube, TikTok, Instagram, Facebook, X, Vimeo o MP4. Recibe fotogramas JPG, PNG o WebP por intervalo, cantidad o marca de tiempo, como URLs firmadas o en un ZIP. Sin descargadores, sin servidores de FFmpeg y sin proxies que mantener.
- 60 créditos gratis cada mes
- 1 crédito = 1 minuto de video
- Los trabajos fallidos no se cobran
curl -X POST "https://api.getvideoframes.com/v1/jobs?wait=true" \
-H "Authorization: Bearer $GVF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"resolution":1080,"every":2,"format":"jpg","url":"https://www.youtube.com/shorts/VIDEO_ID"}'Pruébalo ya
Pega un enlace y míralo funcionar
Es el mismo proceso que usa la API. La vista previa gratis devuelve seis fotogramas de 640 px. Con una API key eliges la resolución: 720p en el plan gratis y hasta 2160p con un paquete o una suscripción.
Inicio rápido
De cero a fotogramas en tres pasos
- 01
Crea una cuenta gratis
Entra con un código de un solo uso enviado a tu correo. Recibes 60 créditos al instante y cada mes: 60 minutos de video.
- 02
Crea una API key
Las claves empiezan por gvf_live_. Solo guardamos un hash: cópiala una vez y guárdala en una variable de entorno.
- 03
Envía la URL del video
POST /v1/jobs con ?wait=true devuelve los fotogramas en la misma respuesta para la mayoría de videos cortos. Los trabajos largos devuelven un id para consultar o un webhook.
Respuesta
{
"id": "6d31d862-2fbe-4304-92bc-44d78fd8d36c",
"status": "completed",
"platform": "youtube",
"duration_seconds": 19.06,
"frames_count": 10,
"frames_failed": 0,
"credits_charged": 1,
"width": 1920,
"height": 1080,
"frames": [
{ "index": 1, "timestamp": 0, "status": "ok", "url": "https://…/frame_00001.jpg?X-Amz-Signature=…", "error": null },
{ "index": 2, "timestamp": 2, "status": "ok", "url": "https://…/frame_00002.jpg?X-Amz-Signature=…", "error": null }
],
"zip_url": null,
"expires_at": "2026-10-01T14:00:21Z"
}Modos de extracción
Pide fotogramas como los necesita tu flujo
Cada trabajo decodifica el video una vez y devuelve los fotogramas en orden con su marca de tiempo exacta en segundos.
Cantidad
"count": 12N fotogramas repartidos en todo el video o entre start y end. Ideal para storyboards y vistas previas.
Marcas de tiempo
"timestamps": [1.5, 42, 90]Momentos exactos, hasta 500 por trabajo, cobrados por cada diez fotogramas en lugar de por minuto.
Rango
"start": 30, "end": 90Procesa solo una parte de un video largo y paga solo los minutos procesados.
Precios
Pagas por minuto de video. Empiezas gratis.
Un crédito equivale a un minuto de video, con hasta 100 fotogramas incluidos en ese minuto. Por ejemplo, 100 créditos cubren 100 minutos. Las marcas de tiempo exactas cuestan un crédito por cada diez fotogramas. Los trabajos fallidos nunca se cobran.
Gratis
$0/mes
60 créditos = 60 min de video
- Videos de hasta 10 min
- 300 fotogramas por trabajo
- Fotogramas de hasta 1280 px de ancho
- Enlaces de descarga por 1 día
- 2 trabajos activos a la vez
- 10 peticiones por minuto
Paquete de créditos
No caduca$10pago único
500 créditos = 500 min de video
- Videos de hasta 60 min
- 2000 fotogramas por trabajo
- Fotogramas de hasta 3840 px de ancho
- Enlaces de descarga por 1 día
- 2 trabajos activos a la vez
- 10 peticiones por minuto
Starter
$19/mes
1500 créditos = 1500 min de video
- Videos de hasta 60 min
- 2000 fotogramas por trabajo
- Fotogramas de hasta 3840 px de ancho
- Enlaces de descarga por 7 días
- 3 trabajos activos a la vez
- 60 peticiones por minuto
Pro
Popular$49/mes
5000 créditos = 5000 min de video
- Videos de hasta 120 min
- 5000 fotogramas por trabajo
- Fotogramas de hasta 3840 px de ancho
- Enlaces de descarga por 7 días
- 5 trabajos activos a la vez
- 120 peticiones por minuto
Scale
$199/mes
25.000 créditos = 25.000 min de video
- Videos de hasta 180 min
- 10.000 fotogramas por trabajo
- Fotogramas de hasta 3840 px de ancho
- Enlaces de descarga por 7 días
- 10 trabajos activos a la vez
- 300 peticiones por minuto
Precios en USD. Las suscripciones se renuevan cada mes y reinician los créditos mensuales; los créditos de paquete se suman y no caducan. Cancela o cambia de plan cuando quieras desde el portal de facturación.
Fuentes compatibles
Enlaces públicos de las plataformas que pegan tus usuarios
YouTube (videos y Shorts), TikTok, Reels y publicaciones de Instagram, videos y Reels de Facebook, X, Vimeo, enlaces compartidos de Google Drive y cualquier URL directa .mp4, .mov o .webm.
Solo se procesan videos públicos. Las publicaciones privadas, eliminadas o que requieren inicio de sesión devuelven el error PrivateContent y no cuestan nada.
Referencia
Endpoints
- POST/v1/jobs
- Crea un trabajo de extracción. Añade ?wait=true para esperar hasta 50 s el resultado.
- GET/v1/jobs/:id
- Estado, fotogramas con URLs firmadas (cada uno tiene status ok o error) y zip_url cuando lo pides.
- GET/v1/jobs
- Tus trabajos recientes, del más nuevo al más antiguo (limit, skip, status).
- GET/v1/usage
- Plan, saldo de créditos, límites y consumo del periodo.
- GET/v1/pricing
- Lista pública de precios (sin clave).
- url
- Obligatorio. Enlace de video público o URL directa de video.
- mode
- interval, count o timestamps. Se deduce de every / count / timestamps.
- format
- jpg (por defecto), png o webp.
- resolution
- 240, 360, 480, 720, 1080, 1440 o 2160. Por defecto 1080. El plan gratis llega hasta 720p: si pides más, responde ResolutionNotAllowed y no entrega enlaces. Si el video no tiene esa versión, el trabajo se completa con la inferior y resolution_note lo explica. Los fotogramas nunca se amplían.
- max_width
- Reducción extra opcional, nunca por encima de la resolución pedida.
- output
- urls (por defecto), zip o both. Más de 300 fotogramas siempre van en ZIP.
- webhook_url
- URL HTTPS que recibe job.completed o job.failed con el trabajo completo.
Errores
Los errores devuelven JSON con data.name (InvalidUrl, ResolutionNotAllowed, PrivateContent, VideoTooLong, TooManyFrames, InsufficientBalance, RateLimited…) y un data.userMessage breve que puedes mostrar a tus usuarios. Si no hay credencial, es AuthenticationRequired. Un header que no sea "Authorization: Bearer gvf_live_…" ni "X-API-Key" es InvalidApiKey con data.reason "malformed". Una clave bien formada, desconocida o revocada, es InvalidApiKey con data.reason "invalid".
Descargar la especificación OpenAPI 3.1MCP remoto · Disponible
Usa la API desde Claude, ChatGPT o Cursor
Pega el enlace de un video en tu chat de IA y recibe los fotogramas, sin programar. El servidor MCP usa tu API key y los mismos créditos que la API REST.
URL del servidor
https://mcp.getvideoframes.com/mcp- 01Crea una API key gratis en el dashboard.
- 02Añade la URL del servidor como conector personalizado o servidor MCP en tu cliente.
- 03Pega la clave gvf_live_ en la página de autorización y pide los fotogramas.
FAQ
Preguntas frecuentes
- ¿Cuánto cuesta la API de fotogramas de video?
- Cada cuenta recibe 60 créditos gratis al mes, es decir 60 minutos de video. Un crédito procesa un minuto con hasta 100 fotogramas. Por ejemplo, 100 créditos cubren 100 minutos. Después puedes comprar 500 créditos por 10 USD (no caducan) o suscribirte: Starter 19 USD por 1.500 créditos, Pro 49 USD por 5.000 y Scale 199 USD por 25.000 al mes.
- ¿Puedo extraer fotogramas de un video de YouTube con una API?
- Sí. Envía la URL del video o del Short a POST /v1/jobs con resolution (por defecto 1080), un intervalo, una cantidad o marcas de tiempo. El plan gratis acepta hasta 720p. Si pides más, hay un error y no hay enlaces. Los planes de pago y los paquetes pueden pedir hasta 2160p. Si esa versión no existe, recibes la inferior y resolution_note.
- ¿Cuánto tiempo se guardan los fotogramas?
- Las cuentas gratis conservan los enlaces 1 día y los planes de pago 7 días. Después los archivos se borran automáticamente, así que cópialos a tu almacenamiento si los necesitas más tiempo.
- ¿Qué pasa si un video falla?
- Si algunos instantes no se pueden decodificar, el trabajo se completa igual: esos fotogramas tienen status "error" y url null, y solo se cobran los decodificados. Las publicaciones privadas, los videos eliminados, los enlaces no compatibles y los trabajos sin ningún fotograma devuelven un error estructurado y tu saldo queda igual.
- ¿Hay límite de duración del video?
- Gratis procesa hasta 10 minutos por trabajo, los paquetes de créditos 60, Starter 60, Pro 120 y Scale 180. Usa start y end para procesar un tramo de un video más largo.
- ¿Hay límites de peticiones?
- Gratis permite 10 peticiones de trabajos por minuto y 2 trabajos en curso; los planes de pago permiten de 60 a 300 por minuto y de 3 a 10 trabajos simultáneos. Consultar trabajos y uso permite 600 peticiones por minuto en todos los planes. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos Unix); un 429 además envía Retry-After en segundos.
Lanza la extracción de fotogramas hoy
Crea una clave gratis, pega una petición y ve tus primeros fotogramas en segundos.