Miniatura de un vídeo
Un vídeo sin imagen de portada es una casilla gris que pide un clic a ciegas. Este endpoint extrae una sola imagen fija en el segundo exacto que usted indique, para que la miniatura realmente represente el momento que vale la pena mostrar.
Ejecútela online
Ejecute esto en nuestros servidores con su cuenta. Las herramientas gratuitas corren en su navegador; esta cobra de su saldo del KIT según el precio de arriba.
El problema de la casilla gris
Los navegadores y reproductores muestran por defecto nada, un rectángulo negro o un fotograma elegido al azar que suele caer justo en medio de una transición borrosa, a menos que algo entregue explícitamente una imagen de portada. Ese comportamiento por defecto cuesta clics, porque la gente decide si va a ver el vídeo en la medio segundo antes de presionar play, y un fotograma malo se lee como una carga rota aunque el vídeo en sí esté perfecto. video.thumbnail resuelve el problema puntual de sacar un fotograma representativo de un archivo de vídeo bajo demanda.
Cómo funciona la extracción
Envíe POST a /video/thumbnail con el vídeo de origen y el segundo exacto que quiere capturar, y la respuesta llega de inmediato como un task_id mientras la extracción del fotograma corre en segundo plano. La imagen fija llega mediante una llamada de webhook firmada en cuanto está lista, o queda disponible en un enlace firmado válido por 24 horas si eso encaja mejor con su flujo de recuperación.
Por qué el segundo exacto importa más de lo que parece
La decodificación de vídeo funciona alrededor de fotogramas clave: imágenes completas guardadas periódicamente a lo largo del archivo, con los fotogramas intermedios reconstruidos a partir de las diferencias contra ellos. Llegar exactamente al segundo solicitado a veces implica decodificar hacia adelante desde el fotograma clave más cercano en lugar de simplemente saltar a él, razón por la cual un extractor de miniaturas necesita decodificar vídeo de verdad, no solo leer el encabezado de un archivo. Las imágenes de portada forman parte de la entrega de vídeo desde que los primeros reproductores web necesitaron algo que mostrar antes de que arrancara la reproducción, y la mecánica de fondo no ha cambiado mucho.
Dónde encajan las miniaturas en un sistema más grande
Un sistema de gestión de contenidos que recibe vídeos en masa suele necesitar una miniatura desde el momento en que el vídeo llega, mucho antes de que alguien revise el metraje manualmente: una página de catálogo, un panel de administración y una grilla de resultados de búsqueda necesitan mostrar algo de inmediato. Como la tarea se cobra por solicitud y una sola vez por vídeo sin importar cuántas veces se muestre después, generar miniaturas como parte del ingreso inicial, en lugar de bajo demanda en cada vista de página, mantiene una biblioteca de medios predecible a escala.
Qué puede hacer con ella
Imágenes de portada para catálogo
Una biblioteca de vídeo genera una miniatura para cada archivo subido al momento del ingreso, así las páginas de exploración y búsqueda nunca muestran un espacio vacío.
Marcadores de capítulo para grabaciones largas
Una plataforma de educación en línea extrae una miniatura al inicio de cada segmento de lección para construir un selector visual de capítulos para los estudiantes.
Vista previa para compartir en redes
Una plataforma de publicación captura un fotograma unos segundos después del inicio del clip, pasado el típico intro en negro, para usarlo como imagen de vista previa al compartir en redes sociales.
Grilla de revisión de moderación
Una plataforma de contenido generado por usuarios captura un fotograma a mitad del vídeo de cada carga para llenar una cola de moderación que los revisores puedan escanear visualmente.
Preguntas frecuentes
¿Cómo obtengo una miniatura de un vídeo con la API?
Envíe el vídeo de origen y el segundo que desea por POST a /video/thumbnail, guarde el task_id devuelto y reciba la imagen fija por webhook o mediante un enlace firmado válido por 24 horas.
¿Es gratis la API de miniaturas de vídeo?
No, no hay plan gratuito ni prueba; cuesta $0.077 por solicitud más $0.0045 por vídeo, y una extracción fallida nunca se cobra.
¿Puedo elegir cualquier segundo para la miniatura?
Sí, usted indica el segundo exacto que quiere capturar, en lugar de depender de un fotograma elegido al azar o por defecto.
¿En qué formato se entrega la miniatura?
El endpoint devuelve una imagen fija estándar extraída del fotograma solicitado, lista para usarse directamente como portada o vista previa.
¿Puedo generar miniaturas para muchos vídeos a la vez?
Sí, envíe una tarea asíncrona por vídeo y reciba cada miniatura por webhook a medida que se complete, algo que encaja de forma natural en flujos de ingreso masivo.
¿Ya está disponible este endpoint?
Está en despliegue en este momento, así que verifique el estado del endpoint antes de enviar tráfico de producción porque todavía no acepta trabajos.
¿La duración del vídeo afecta el precio?
No, la extracción de miniaturas se cobra por solicitud más una tarifa fija por vídeo, no según la duración.
¿Se guarda mi vídeo después de generar la miniatura?
No, el vídeo de origen y la imagen extraída se eliminan después del período de retención y nunca se usan para entrenamiento.
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, y pronto desde nuestra app, el email y Telegram.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/video/thumbnail \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"…"}'const res = await fetch("https://api.kit.forhosting.com/video/thumbnail", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"input": "…"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/video/thumbnail",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"input": "…"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/video/thumbnail", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"input":"…"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"input":"…"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/video/thumbnail", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"input": "…"
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "video.thumbnail",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Límites
max_mb | 500 |
max_minutes | 60 |
max_megapixels | 3.9 |
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |