API para desenvolvedores

Comprima vídeo para um tamanho de arquivo exato

Envie uma URL pública de vídeo ou faça upload de um arquivo. O VidSmaller executa a compressão de forma assíncrona, informa o progresso e devolve um resultado pronto para download.

Baixar OpenAPIBaixar coleção do PostmanAbrir no Postman
Atualizado
Atualizado: 2026-10-17
Limites verificados
Limites verificados: 2026-09-14
Usa os seus créditos do VidSmaller
Usa os seus créditos do VidSmaller
Nesta página

Comece em 3 passos

Crie uma chave, envie um vídeo e depois consulte a tarefa ou aguarde um webhook assinado.

  1. 1

    Criar uma chave

    Dê um nome à chave no seu painel. Copie a chave de API e o segredo do webhook quando aparecerem; ambos são exibidos apenas uma vez.

  2. 2

    Criar uma tarefa

    Envie uma URL pública ou faça upload de um arquivo, depois escolha target_size_mb e, opcionalmente, as configurações de codec, resolução e formato.

  3. 3

    Obter o resultado

    Consulte o status da tarefa ou receba um webhook assinado. Tarefas concluídas incluem uma URL de download autenticada e de curta duração.

Endpoints gratuitos somente de leitura

As requisições de limites de plataforma e de estimativa não precisam de chave de API e permitem 600 requisições por hora por IP.

Um único fluxo de compressão

As tarefas autenticadas usam os mesmos créditos, limites de arquivo, acesso a codecs e limites de pico do compressor web.

Duas opções de entrada

Use uma URL direta e pública de vídeo ou solicite uma URL de upload assinada para um arquivo local.

Contrato v1 estável

Novos campos podem ser adicionados, mas os campos v1 existentes não mudarão de significado.

Autenticação e créditos

Apenas as tarefas de compressão e os uploads exigem autenticação. Os endpoints somente de leitura de plataformas e estimativas são públicos.

Chave de API Bearer

Crie chaves no painel API Keys. Guarde o valor completo com segurança, pois ele não pode ser exibido novamente.

Authorization: Bearer $VIDSMALLER_API_KEY

Saldo de créditos compartilhado

A API não tem um plano separado. As tarefas reservam créditos ao serem criadas, são acertadas conforme o tempo real de codificação e reembolsadas automaticamente quando o processamento falha.

/api/v1/platforms

Retorna todos os limites de upload acompanhados pelo VidSmaller, junto com alvos de compressão seguros, links de origem e a data em que cada limite foi verificado.

GET

Retorna 8 plataformas. Não requer autenticação nem parâmetros.

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

Campos da resposta

statedLimitMbnumber

O limite de upload anunciado pela plataforma para o seu nível principal.

safeTargetMbnumber

Um alvo de compressão ligeiramente menor, que deixa margem para a variação do codificador.

tierNotestring | null

Uma ressalva para quando o limite anunciado depende do tipo de conta, do app ou do acesso à API.

tiers[]array

Todos os níveis documentados (gratuitos, pagos, de bots ou específicos de cliente) e respectivas notas.

verifiedAtdate

A data em que uma pessoa verificou pela última vez a documentação oficial da plataforma.

sources[]array

As páginas de origem usadas para verificar o limite.

/api/v1/estimate

Verifica se um arquivo cabe num destino e estima o resultado de uma configuração de compressão. Os campos de consulta do GET e o corpo JSON do POST usam os mesmos nomes.

GET · POSTNão requer chave de API
curl -s "https://vidsmaller.com/api/v1/estimate?sizeMb=150.7&durationSeconds=596&platform=discord"

Campos da requisição

sizeBytesinteger

Tamanho do arquivo de origem em bytes. Obrigatório, a menos que sizeMb seja informado.

sizeMbnumber

Tamanho da origem em MiB, onde 1 MB equivale a 1.048.576 bytes.

durationSecondsnumber

Duração opcional. Altamente recomendada, pois sem ela não é possível estimar qualidade e bitrate.

width, heightinteger

Dimensões opcionais da origem. Necessárias apenas ao estimar mudanças de resolução.

platformstring

Chave de plataforma opcional, obtida em /api/v1/platforms. Aplica o alvo seguro dessa plataforma.

targetMbnumber

Limite máximo de tamanho de arquivo personalizado e opcional. Substitui o alvo da plataforma selecionada.

settingsobject

Configurações opcionais do compressor: mode, preset, targetSizeMb, crf, resolution, maxResolution, bitrateKbps, codec e outputFormat.

Campos da resposta

verdictstring

fits_as_is, compress_recommended ou no_target. Seguro para uso na lógica da aplicação.

estimateobject | null

Resultado previsto para as configurações solicitadas. Null quando os dados informados não permitem uma estimativa honesta.

recommendationobject | null

Configurações que devem caber no alvo, incluindo o bitrate de vídeo estimado e orientações de qualidade.

notes[]string[]

Ressalvas em linguagem simples, úteis para exibir ao usuário final.

compressUrlstring

A ferramenta web do VidSmaller correspondente, para quem quiser concluir o trabalho manualmente.

Exemplo de resposta

{
  "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

Cria uma tarefa de compressão assíncrona que mira o target_size_mb. Use uma URL de origem pública ou um token de arquivo enviado.

POSTRequer chave de API Bearer

Opção A: URL pública de vídeo

Use source_url para um arquivo de vídeo direto e publicamente acessível. O VidSmaller verifica o tamanho real da origem 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"
  }'

Opção B: upload de arquivo local

Solicite uma URL de upload assinada, envie os bytes diretamente ao armazenamento com PUT e depois crie a tarefa com o upload_token retornado.

# 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 da requisição

source_urlHTTPS URL

URL direta e pública do vídeo. Use este campo ou upload_token, nunca ambos.

upload_tokenstring

Token retornado após solicitar uma URL de upload assinada. Use este campo ou source_url.

target_size_mbnumber

Limite máximo de saída em MiB (obrigatório).

codecstring

h264 por padrão, ou h265 quando o recurso pago da conta permitir.

max_resolutionstring

Limite opcional: 2160p, 1440p, 1080p, 720p, 576p, 480p ou 360p.

output_formatstring

Contêiner de saída opcional: mp4 por padrão, mkv, webm ou mov.

webhook_urlHTTPS URL

Callback opcional para eventos terminais. Endereços de redes privadas e redirecionamentos são rejeitados.

Verificar o status e baixar

Consulte até que job.status seja completed ou failed. Uma tarefa concluída retorna uma download_url autenticada e de curta duração. Use a mesma chave bearer nas requisições de status e de download.

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

Webhooks assinados

Receba um callback em vez de fazer polling quando uma tarefa atinge um estado terminal.

Os eventos são video.job.completed, video.job.failed e video.job.expired.

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

Use o segredo de assinatura de webhook exibido quando a chave de API é criada. O cabeçalho de assinatura começa com v1=.

Erros

Os erros usam respostas JSON. O código de status indica se você deve corrigir a requisição, autenticar-se novamente, comprar créditos ou tentar mais tarde.

400

Campo da requisição inválido ou ausente.

Leia a mensagem de erro e corrija o payload.

401

Chave de API ausente, inválida ou excluída.

Envie uma chave bearer válida ou crie uma nova.

402

Créditos insuficientes para a tarefa.

Adicione créditos e crie a tarefa novamente.

404

Tarefa ou download não encontrados para esta chave.

Verifique o ID e use a chave que criou a tarefa.

409

O upload ou a tarefa não está no estado necessário.

Verifique o status atual antes de repetir a ação.

429

Limite de requisições ou de concorrência atingido.

Aguarde e tente novamente com backoff.

500

O VidSmaller não conseguiu concluir a requisição.

Tente novamente mais tarde. Entre em contato com o suporte se o problema continuar.

Limites e uso justo

A API segue os mesmos limites de produto do compressor web.

  • Os endpoints públicos somente de leitura permitem 600 requisições por hora por IP.
  • As tarefas de compressão usam os créditos, os limites de tamanho de arquivo, o acesso a codecs e os limites de pico da sua conta.
  • A API v1 pode adicionar campos de resposta, mas os campos existentes não mudarão de significado.
  • O uso comercial é permitido. Um link para o VidSmaller é apreciado, mas não obrigatório.

Se um limite de plataforma estiver incorreto ou uma requisição à API se comportar de forma inesperada, escreva para support@vidsmaller.com

Recursos relacionados

Calculadora de compressão de vídeoLimites de upload do DiscordTermos de Serviço
Voltar ao início