API de miniaturas de video: extrae un fotograma de portada en cualquier marca de tiempo
Dale a Fotovid una marca de tiempo y te devuelve ese fotograma exacto como imagen alojada, lista para insertar directamente como vista previa de galería, miniatura de feed o portada de video.
curl -X POST https://api.fotovid.co/v1/video/extract-cover \
-H "Authorization: Bearer p6_YOUR_KEY_ID:YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.yoursite.com/clip.mp4",
"params": {
"at": 3
}
}'Por qué extraer un solo fotograma es más difícil de lo que parece
Una miniatura de video es conceptualmente trivial: te posicionas en una marca de tiempo, decodificas un fotograma y lo codificas como imagen. En la práctica, o ejecutas ffmpeg tú mismo o dependes de una plataforma de medios sobrecargada. Incluir un binario de ffmpeg supera con creces los límites de tamaño y memoria de un entorno serverless, los cold starts se ralentizan, y decodificar una fuente grande puede superar el timeout de una función. Y casi nunca necesitas todo el conjunto de herramientas — solo necesitas sacar un fotograma.
- Los binarios de ffmpeg son demasiado grandes para la mayoría de los paquetes serverless y consumen el presupuesto de cold start
- Decodificar un video grande para extraer un solo fotograma puede superar los límites de memoria y timeout de la función
- Tienes que obtener la fuente, ejecutar el proceso y luego subir tú mismo el resultado a algún sitio
- Las plataformas de medios completas incluyen transformaciones, almacenamiento y CDN que no necesitas solo para conseguir una portada
Parámetros de la solicitud
POST /v1/video/extract-cover
| Field | Type | Default | Description |
|---|---|---|---|
| source_url* | string (URL) | — | URL HTTPS del video de origen (se lee mediante HTTP Range) |
| params.at | number | 1 | Segundos dentro del video en los que se extrae el fotograma |
Tu primera llamada en tres pasos
- 1Obtén una clave de API gratuita
Regístrate y crea una clave. Autenticas cada solicitud con un encabezado Authorization: Bearer p6_<key_id>:<secret>. Las claves nuevas empiezan con créditos de uso gratuitos, así que puedes conectar las miniaturas antes de pagar nada.
- 2Llama a POST /v1/video/extract-cover
Envía un cuerpo JSON con source_url apuntando a la URL https de tu video, junto con un objeto params donde indicas la marca de tiempo que quieres capturar (como una cadena HH:MM:SS.mmm o en segundos). Fotovid obtiene la fuente, decodifica el fotograma en ese punto y lo codifica como imagen en nuestra infraestructura — sin ffmpeg en tu stack.
- 3Usa la URL de la imagen alojada que se devuelve
La respuesta es un JSON plano con id, type y una url alojada por Fotovid que apunta al fotograma extraído, junto con un expires_at. Renderízala directamente como miniatura o portada, o descárgala y guarda tu propia copia en tu bucket para controlar su tiempo de vida.
Preguntas frecuentes
Lánzalo con una sola llamada a la API
Consigue una key gratis y haz tu primera llamada en menos de cinco minutos.