API para desarrolladores

Comprime vídeo a un tamaño de archivo exacto

Envía una URL pública de vídeo o sube un archivo. VidSmaller ejecuta la compresión de forma asíncrona, informa del progreso y devuelve un resultado descargable.

Descargar OpenAPI Descargar colección de Postman Abrir en Postman

Actualizado: Actualizado: 2026-10-17
Límites verificados: Límites verificados: 2026-09-14
Usa tus créditos de VidSmaller: Usa tus créditos de VidSmaller

En esta página

Empieza en 3 pasos

Crea una clave, envía un vídeo y luego consulta el trabajo o espera un webhook firmado.

1
Crea una clave
Dale un nombre a la clave en tu panel. Copia la clave de API y el secreto del webhook cuando aparezcan; ambos se muestran una sola vez.
2
Crea un trabajo
Envía una URL pública o sube un archivo y luego elige target_size_mb y, opcionalmente, los ajustes de códec, resolución y formato.
3
Obtén el resultado
Consulta el estado del trabajo o recibe un webhook firmado. Los trabajos completados incluyen una URL de descarga autenticada y de corta duración.

Endpoints gratuitos de solo lectura

Las solicitudes de límites por plataforma y de estimación no necesitan clave de API y permiten 600 solicitudes por hora y por IP.

Un único flujo de compresión

Los trabajos autenticados usan los mismos créditos, límites de archivo, acceso a códecs y límites de ráfaga que el compresor web.

Dos opciones de entrada

Usa una URL pública directa de vídeo o solicita una URL de subida firmada para un archivo local.

Contrato v1 estable

Pueden añadirse campos nuevos, pero los campos existentes de v1 no cambiarán de significado.

Autenticación y créditos

Solo los trabajos de compresión y las subidas requieren autenticación. Los endpoints de solo lectura de plataformas y estimación son públicos.

Clave de API Bearer

Crea claves en el panel de claves de API. Guarda el valor completo de forma segura, porque no podrá volver a mostrarse.

Authorization: Bearer $VIDSMALLER_API_KEY

Saldo de créditos compartido

La API no tiene un plan independiente. Los trabajos reservan créditos al crearse, se liquidan según el tiempo real de codificación y se reembolsan automáticamente cuando el procesamiento falla.

/api/v1/platforms

Devuelve todos los límites de subida que VidSmaller monitoriza, junto con objetivos de compresión seguros, enlaces a las fuentes y la fecha en que se verificó cada límite.

GET

Devuelve 8 plataformas. No requiere autenticación ni parámetros.

curl -s https://vidsmaller.com/api/v1/platforms

Campos de la respuesta

statedLimitMbnumber

El límite de subida anunciado por la plataforma para su nivel principal.

safeTargetMbnumber

Un objetivo de compresión algo más bajo que deja margen para la variación del codificador.

tierNotestring | null

Una salvedad cuando el límite anunciado depende del tipo de cuenta, la aplicación o el acceso a la API.

tiers[]array

Todos los niveles documentados (gratuitos, de pago, de bots o específicos de un cliente) y sus notas.

verifiedAtdate

La fecha en que una persona consultó por última vez la documentación oficial de la plataforma.

sources[]array

Las páginas de origen utilizadas para verificar el límite.

/api/v1/estimate

Comprueba si un archivo encaja en un destino y estima el resultado de una configuración de compresión. Los campos de consulta GET y el cuerpo JSON de POST usan los mismos nombres.

GET · POSTNo se requiere clave de API

curl -s "https://vidsmaller.com/api/v1/estimate?sizeMb=150.7&durationSeconds=596&platform=discord"

Campos de la solicitud

sizeBytesinteger

Tamaño del archivo de origen en bytes. Obligatorio salvo que se indique sizeMb.

sizeMbnumber

Tamaño de origen en MiB, donde 1 MB equivale a 1.048.576 bytes.

durationSecondsnumber

Duración opcional. Muy recomendable, porque sin ella no es posible estimar la calidad ni el bitrate.

width, heightinteger

Dimensiones de origen opcionales. Solo son necesarias al estimar cambios de resolución.

platformstring

Clave de plataforma opcional de /api/v1/platforms. Aplica el objetivo seguro de esa plataforma.

targetMbnumber

Límite máximo de tamaño de archivo personalizado y opcional. Prevalece sobre el objetivo de la plataforma seleccionada.

settingsobject

Ajustes opcionales del compresor: mode, preset, targetSizeMb, crf, resolution, maxResolution, bitrateKbps, codec y outputFormat.

Campos de la respuesta

verdictstring

fits_as_is, compress_recommended o no_target. Se puede usar con seguridad en la lógica de la aplicación.

estimateobject | null

Resultado previsto para los ajustes solicitados. Null cuando los datos de entrada no permiten una estimación fiable.

recommendationobject | null

Ajustes con los que se espera cumplir el objetivo, incluido el bitrate de vídeo estimado y orientaciones sobre la calidad.

notes[]string[]

Salvedades en lenguaje sencillo, útiles para mostrar al usuario final.

compressUrlstring

La herramienta web de VidSmaller correspondiente para quien prefiera terminar el trabajo manualmente.

Respuesta de ejemplo

{
  "ok": true,
  "input": { "sizeBytes": 158020403, "sizeMb": 150.7, "durationSeconds": 596 },
  "target": {
    "platform": "discord",
    "safeTargetMb": 19,
    "statedLimitMb": 20,
    "verifiedAt": "2026-09-14"
  },
  "verdict": "compress_recommended",
  "fitsAsIs": false,
  "estimate": {
    "settings": { "mode": "preset", "preset": "balanced", "codec": "libx264" },
    "outputMb": 90.4,
    "savedPercent": 40,
    "fitsTarget": false,
    "jobSeconds": 123
  },
  "recommendation": {
    "settings": { "mode": "target_size", "targetSizeMb": 19 },
    "outputMb": 19,
    "quality": { "videoKbps": 134, "verdict": "rough" }
  }
}

/api/v1/video/jobs

Crea un trabajo de compresión asíncrono que apunta a target_size_mb. Usa una URL de origen pública o un token de archivo subido.

POSTSe requiere clave de API Bearer

Opción A: URL pública de vídeo

Usa source_url para un archivo de vídeo directo y accesible públicamente. VidSmaller comprueba el tamaño real del origen antes de reservar créditos.

curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/input.mp4",
    "target_size_mb": 25,
    "codec": "h264",
    "max_resolution": "1080p",
    "webhook_url": "https://example.com/webhooks/vidsmaller"
  }'

Opción B: subida de archivo local

Solicita una URL de subida firmada, envía los bytes con PUT directamente al almacenamiento y luego crea el trabajo con el upload_token devuelto.

# 1. Request a one-hour signed upload URL
curl -s https://vidsmaller.com/api/v1/video/uploads \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"input.mp4","file_size":52428800,"content_type":"video/mp4"}'

# 2. PUT the file to upload.url with the returned Content-Type header
# 3. Create the job with the returned upload_token
curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_token":"UPLOAD_TOKEN","target_size_mb":25}'

Campos de la solicitud

source_urlHTTPS URL

URL pública directa de vídeo. Usa esta opción o upload_token, nunca ambas.

upload_tokenstring

Token devuelto tras solicitar una URL de subida firmada. Usa esta opción o source_url.

target_size_mbnumber

Límite máximo de salida obligatorio, en MiB.

codecstring

h264 por defecto, o h265 cuando la capacidad de pago de la cuenta lo permite.

max_resolutionstring

Límite opcional: 2160p, 1440p, 1080p, 720p, 576p, 480p o 360p.

output_formatstring

Contenedor de salida opcional: mp4 por defecto, mkv, webm o mov.

webhook_urlHTTPS URL

Callback opcional para eventos finales. Se rechazan las direcciones de redes privadas y las redirecciones.

Consultar el estado y descargar

Consulta periódicamente hasta que job.status sea completed o failed. Un trabajo completado devuelve una download_url autenticada y de corta duración. Usa la misma clave bearer para las solicitudes de estado y de descarga.

curl -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  https://vidsmaller.com/api/v1/video/jobs/JOB_ID

Webhooks firmados

Recibe un callback en lugar de hacer sondeos cuando un trabajo alcanza un estado final.

Los eventos son video.job.completed, video.job.failed y video.job.expired.

Verifica x-vidsmaller-signature calculando HMAC-SHA256 sobre timestamp + "." + rawBody.

Usa el secreto de firma del webhook que se muestra al crear la clave de API. La cabecera de firma comienza por v1=.

Errores

Los errores se devuelven en respuestas JSON. El código de estado indica si debes corregir la solicitud, volver a iniciar sesión, comprar créditos o reintentar más tarde.

400

Campo de la solicitud inválido o ausente.

Lee el mensaje de error y corrige el payload.

401

Clave de API ausente, inválida o eliminada.

Envía una clave bearer válida o crea una nueva.

402

Créditos insuficientes para el trabajo.

Añade créditos y vuelve a crear el trabajo.

404

No se encontró el trabajo o la descarga para esta clave.

Comprueba el ID y usa la clave con la que se creó el trabajo.

409

La subida o el trabajo no está en el estado requerido.

Comprueba el estado actual antes de reintentar la acción.

429

Se alcanzó el límite de solicitudes o de concurrencia.

Espera y reintenta con backoff.

500

VidSmaller no pudo completar la solicitud.

Reinténtalo más tarde. Contacta con soporte si el problema continúa.

Límites y uso razonable

La API sigue los mismos límites de producto que el compresor web.

Los endpoints públicos de solo lectura permiten 600 solicitudes por hora y por IP.
Los trabajos de compresión usan los créditos, los límites de tamaño de archivo, el acceso a códecs y los límites de ráfaga de tu cuenta.
La v1 de la API puede añadir campos en la respuesta, pero los campos existentes no cambiarán de significado.
El uso comercial está permitido. Agradecemos un enlace a VidSmaller, aunque no es obligatorio.

Si un límite de plataforma es incorrecto o una solicitud de la API se comporta de forma inesperada, escribe a support@vidsmaller.com

Recursos relacionados

Calculadora de compresión de vídeo Límites de subida de Discord Términos del servicio

Volver al inicio

Comprime vídeo a un tamaño de archivo exacto

Empieza en 3 pasos

Crea una clave

Crea un trabajo

Obtén el resultado

Endpoints gratuitos de solo lectura

Un único flujo de compresión

Dos opciones de entrada

Contrato v1 estable

Autenticación y créditos

/api/v1/platforms

Campos de la respuesta

/api/v1/estimate

Campos de la solicitud

Campos de la respuesta

Respuesta de ejemplo

/api/v1/video/jobs

Opción A: URL pública de vídeo

Opción B: subida de archivo local

Campos de la solicitud

Consultar el estado y descargar

Webhooks firmados

Errores

Límites y uso razonable

Recursos relacionados