API REST

API HTTP com JSON simples por trás do site, do fluxo de autenticação da CLI e do servidor MCP.

URL base

https://xvideodownloader.org

Autenticação

Requisições anônimas funcionam para downloads básicos dentro do limite anônimo. Para uma conta persistente (limites maiores, histórico, SVIP), envie Authorization: Bearer <token> — obtenha um token com o comando auth login da CLI ou entrando no site.

Limites de uso

Plano grátis (anônimo ou registrado): 2 downloads/dia, máximo 720p, 25 MB por arquivo. SVIP vitalício: sem limite diário, sem teto de qualidade ou tamanho. Aplicado por IP em requisições anônimas e por conta quando autenticado.

Endpoints

POST/api/download

Cria uma tarefa de download a partir da URL de um post do X/Twitter.

GET/api/downloads/{id}

Obtém o status e os metadados de uma tarefa de download.

GET/api/file/{id}

Redirecionamento 302 para o arquivo baixado. Use ?dl=1 para contar na sua cota diária; sem ele, é só uma pré-visualização.

GET/api/downloads

Lista seu histórico de downloads. Requer autenticação.

DELETE/api/downloads/{id}

Exclui um registro de download. Não é possível excluir uma tarefa em andamento.

GET/api/user/usage

Uso de hoje em relação ao limite diário do seu plano.

GET/api/user/subscription

Plano atual e, para assinantes antigos, o status da assinatura.

Códigos de erro

EMPTY_URL	Nenhuma URL informada
INVALID_URL_FORMAT	A URL não começa com http(s)
UNSUPPORTED_HOST	Somente x.com e twitter.com são suportados
RATE_LIMIT	Limite diário de downloads atingido
FILE_SIZE_LIMIT	O vídeo excede o tamanho máximo do plano
VIDEO_NOT_FOUND	Não foi possível encontrar ou extrair o vídeo
PRIVATE_TWEET	O post é privado ou protegido
GEO_BLOCKED	O conteúdo de origem tem restrição geográfica

Exemplo

Crie um download e consulte até que termine:

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

Especificação OpenAPI

Esquema completo de requisições e respostas no formato OpenAPI 3.0, para geração de código ou importação em ferramentas de API:

/openapi.json →