Miniatura de un vídeo
Extraiga un fotograma del segundo exacto que indique y úselo como portada, para que su vídeo deje de recibir al público con un recuadro negro o una imagen borrosa entre escenas antes de pulsar reproducir. Paga por uso, sin suscripción.
Esta tarea no está disponible ahora mismo, así que no se puede contratar. No se cobra nada por ella.
Cómo funciona y APIUn vídeo sin imagen de portada es una casilla gris que pide un clic a ciegas.
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.
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.
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
¿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.
¿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.
¿Por qué no dejar que el reproductor elija la portada?
Por su cuenta, los reproductores no muestran nada, un rectángulo negro o un fotograma automático que suele ser un borrón entre escenas. La gente decide si mira en medio segundo, y una mala imagen parece un archivo dañado.
¿Qué segundo conviene para la vista previa al compartir?
Para la vista previa de un enlace, elija un momento unos segundos después del inicio, pasada la típica entrada en negro. En lecciones, tome el comienzo de cada parte; para una cuadrícula de revisión, sirve un fotograma de la mitad del vídeo.
¿Cómo recibo la miniatura?
El fotograma se extrae en segundo plano después de enviar el vídeo y el segundo deseado. Cuando está lista, la imagen le espera en un enlace de descarga válido durante 24 horas.
Herramientas relacionadas
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
Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. Esta capacidad está disponible actualmente mediante la API, no como herramienta interactiva en la Web.
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 '{"video":"https://example.com/clip.mp4"}'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({
"video": "https://example.com/clip.mp4"
})
});
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={
"video": "https://example.com/clip.mp4"
},
)
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" => '{"video":"https://example.com/clip.mp4"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"video":"https://example.com/clip.mp4"}`)
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
{
"video": "https://example.com/clip.mp4"
}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. |
Notas técnicas
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.
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.
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.
Preguntas técnicas
¿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.
¿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.