← Desarrolladores

API REST

API HTTP con JSON simple que da soporte al sitio web, al flujo de autenticación de la CLI y al servidor MCP.

URL base

https://xvideodownloader.org

Autenticación

Las peticiones anónimas funcionan para descargas básicas dentro del límite anónimo. Para una cuenta persistente (límites más altos, historial, SVIP), envía Authorization: Bearer <token>; obtén un token con el comando auth login de la CLI o iniciando sesión en el sitio.

Límites de uso

Plan gratuito (anónimo o registrado): 2 descargas/día, máximo 720p, 25 MB por archivo. SVIP de por vida: sin límite diario ni tope de calidad o tamaño. Se aplica por IP en peticiones anónimas y por cuenta al autenticarse.

Endpoints

POST/api/download

Crea una tarea de descarga a partir de la URL de una publicación de X/Twitter.

GET/api/downloads/{id}

Obtiene el estado y los metadatos de una tarea de descarga.

GET/api/file/{id}

Redirección 302 al archivo descargado. Añade ?dl=1 para que cuente en tu cuota diaria; omítelo para una vista previa de solo lectura.

GET/api/downloads

Lista tu historial de descargas. Requiere autenticación.

DELETE/api/downloads/{id}

Elimina un registro de descarga. No se puede eliminar una tarea en ejecución.

GET/api/user/usage

Uso de hoy frente al límite diario de tu plan.

GET/api/user/subscription

Plan actual y, para suscriptores antiguos, el estado de la suscripción.

Códigos de error

EMPTY_URLNo se proporcionó URL
INVALID_URL_FORMATLa URL no empieza por http(s)
UNSUPPORTED_HOSTSolo se admiten x.com y twitter.com
RATE_LIMITSe alcanzó el límite diario de descargas
FILE_SIZE_LIMITEl video supera el tamaño máximo del plan
VIDEO_NOT_FOUNDNo se pudo encontrar o extraer el video
PRIVATE_TWEETLa publicación es privada o protegida
GEO_BLOCKEDEl contenido tiene restricción geográfica

Ejemplo

Crea una descarga y consúltala hasta que termine:

curl -X POST https://xvideodownloader.org/api/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://x.com/user/status/123456789"}'

Especificación OpenAPI

Esquema completo de peticiones y respuestas en formato OpenAPI 3.0, para generar código o importarlo en herramientas de API:

/openapi.json →