CompressGIF

npx add-mcp 'https://compressgif.net/api/mcp'

Automate GIF compression from scripts with the REST API, or connect an AI client through MCP. Learn how to get an API key, submit a GIF and download the result.

Ative o acesso gratuito à API e crie uma chave

O acesso gratuito à API é um recurso de nuvem separado da ferramenta de navegador. Ele fornece 500 créditos por mês UTC sem cartão, após você entrar com uma conta @gmail.com verificada pelo Google e passar pelo Turnstile, sujeito a um orçamento mensal gratuito de computação de $20.

Crie uma chave de API na página de configurações da conta após a ativação. Todas as chaves da conta compartilham o mesmo pool de créditos, limites de taxa e limites de tarefas não concluídas. Quando o orçamento gratuito de computação for esgotado, novas tarefas gratuitas pausam até o horário de redefinição exibido; tarefas pagas para Desenvolvedores e compressão local no navegador continuam separadamente.

Obtenha uma chave de API gratuita

Crie uma tarefa de upload

Envie uma solicitação multipart com um arquivo GIF e um campo options contendo JSON. O modo target usa bytes decimais em targetBytes; não envie campos de formulário separados para mode ou targetBytes.

Toda solicitação de criação deve incluir uma Idempotency-Key com escopo da conta. Reutilizar a mesma chave com o mesmo arquivo e opções retorna a tarefa original sem reservar créditos novamente.

curl -X POST https://compressgif.net/api/v1/compressions \
  -H "Authorization: Bearer cg_live_xxx" \
  -H "Idempotency-Key: demo-upload-001" \
  -F "file=@animation.gif" \
  -F 'options={"mode":"target","targetBytes":1000000}'

Consulte a tarefa e baixe o resultado

A resposta de criação contém um id de nível superior. Salve-o como JOB_ID e use-o na URL de status; ele não está aninhado dentro de uma propriedade job. A resposta de criação sozinha não contém um link de download. Consulte o endpoint de status mesmo quando a criação reproduz uma tarefa já concluída. Substitua YOUR_JOB_ID no exemplo por esse id e copie result.downloadUrl de uma resposta bem-sucedida para DOWNLOAD_URL antes de executar o comando de download.

Enquanto o status estiver como queued ou processing, result é null. Quando o status for succeeded, leia result.downloadUrl e result.expiresInSeconds. Em caso de failed ou canceled, pare de consultar e inspecione error.code e error.message em vez de tentar baixar novamente.

Consulte a cada poucos segundos e permaneça dentro do limite de leitura da conta. Uma nova consulta de status pode atualizar um link de download expirado enquanto o arquivo ainda estiver acessível. Os links duram até 15 minutos e nunca estendem o acesso ao arquivo além de 24 horas. Consultas, downloads e reprodução idempotente exata não gastam créditos.

JOB_ID='YOUR_JOB_ID'
curl "https://compressgif.net/api/v1/compressions/$JOB_ID" \
  -H "Authorization: Bearer cg_live_xxx"

DOWNLOAD_URL='PASTE_result.downloadUrl_HERE'
curl --fail --location "$DOWNLOAD_URL" -o compressed.gif

Envie uma URL HTTPS

Solicitações de criação em JSON usam sourceUrl e options. O servidor busca apenas URLs HTTPS, valida cada redirecionamento, bloqueia redes privadas e aplica os mesmos limites de tamanho de arquivo que os uploads.

Se um site bloquear CORS no navegador, a importação local de URL pode falhar. A importação de URL via REST ainda é uma tarefa em nuvem e usa sua chave de API, créditos, limites de taxa e regras de retenção.

curl -X POST https://compressgif.net/api/v1/compressions \
  -H "Authorization: Bearer cg_live_xxx" \
  -H "Idempotency-Key: demo-url-001" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://example.com/animation.gif","options":{"mode":"quality"}}'

Leia uso e janelas de redefinição

GET /api/v1/usage retorna { usage }. O objeto usage inclui active pool, limit, used, reserved, remaining, resetAt, windowStart e windowEnd. Solicitações gratuitas de criação são limitadas a 10 rpm, solicitações de criação para Desenvolvedores a 60 rpm e leituras de status ou uso a 120 rpm por conta.

As janelas gratuitas da API são redefinidas pelo mês do calendário UTC. As janelas para Desenvolvedores são redefinidas mensalmente na âncora da assinatura, incluindo assinaturas anuais. Créditos não são acumulados. Contas gratuitas podem ter 2 tarefas não concluídas, contas de Desenvolvedor podem ter 20, e a fila gratuita pode conter 100 tarefas. Uma tarefa gratuita que espera mais de 10 minutos é encerrada e libera sua reserva.

curl https://compressgif.net/api/v1/usage \
  -H "Authorization: Bearer cg_live_xxx"

Configuração do MCP

O endpoint MCP é Streamable HTTP em /api/mcp. Ele expõe compress_gif, get_compression e get_usage e usa a mesma chave de API que o REST.

O MCP aceita URLs HTTPS remotas de GIF. Arquivos locais devem ser enviados via REST; não passe caminhos locais do servidor ou grandes payloads Base64 para a ferramenta MCP.

Chame compress_gif com sourceUrl, um objeto options opcional e uma idempotencyKey obrigatória. Em seguida, passe o id retornado para get_compression. O adaptador envolve a resposta REST em structuredContent.data; o transporte bem-sucedido da ferramenta não significa que a tarefa de compressão foi concluída. Use get_usage com um objeto vazio para verificar seu saldo.

{
  "mcpServers": {
    "compressgif": {
      "url": "https://compressgif.net/api/mcp",
      "headers": { "Authorization": "Bearer cg_live_xxx" }
    }
  }
}

Créditos, modo target e cobrança

Entradas de até 5MB custam 1 crédito no modo quality ou size e 2 créditos no modo target. Entradas acima de 5MB e até 20MB custam 2 créditos, ou 4 créditos no modo target. Cada tentativa de processamento tem um orçamento de 60 segundos e no máximo 8 candidatos codificados.

Falhas de validação, falhas de sistema e tempos limite não gastam créditos do usuário. Um resultado válido que não atinge o target solicitado ainda gasta a cotação divulgada porque o trabalho de computação foi concluído; a tarefa marca targetMet: false.

Os campos credits e cost.credits da tarefa mostram o custo cotado, não a prova de um débito concluído. Os créditos são reservados quando uma tarefa é aceita, liquidados no sucesso e liberados na falha. Verifique /api/v1/usage para o saldo atual de used, reserved e remaining.

Erros, idempotência e limites de taxa

Códigos de erro comuns incluem API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS e FREE_COMPUTE_BUDGET_EXHAUSTED.

401 cobre chaves de API ausentes ou inválidas. 402 é apenas para créditos de usuário esgotados. 403 cobre acesso gratuito à API inativo. 409 cobre conflitos de idempotência. 413 cobre limites de tamanho de entrada na nuvem. 422 cobre dados ou opções de GIF inválidos. 429 cobre limites de taxa de criação/leitura e limites de tarefas não concluídas. 503 cobre pressão temporária na fila ou FREE_COMPUTE_BUDGET_EXHAUSTED; respeite Retry-After quando presente.

Autenticação e manipulação de chaves

Envie Authorization: Bearer YOUR_API_KEY em solicitações de criação, status e uso. A API também aceita o cabeçalho x-api-key. Cookies de login da conta não substituem uma chave de API. Todas as chaves pertencentes a uma conta compartilham permissões e limites.

Mantenha a chave em uma variável de ambiente no servidor ou na configuração protegida do seu cliente de IA. Não a coloque em uma página pública, repositório ou URL de imagem. Se uma chave for exposta, revogue-a nas configurações de chave de API e crie uma substituta. A ferramenta gratuita do navegador não precisa de chave de API.

Opções de compressão e limites de entrada

mode aceita quality, size ou target e o padrão é quality. target requer um targetBytes inteiro positivo, medido em bytes decimais: 100KB é 100000 e 1MB é 1000000. Para uploads multipart, coloque esses campos dentro do campo options codificado em JSON.

O opcional colors aceita auto, 64, 128 ou 256. lossyLevel aceita um inteiro de 0 a 200. width aceita um inteiro de 1 a 4096 e solicita redimensionamento; omita-o para manter as dimensões originais. Nenhuma opção de remoção de quadros ou conversão de formato é suportada.

Uma solicitação processa um GIF. Entradas gratuitas da API são limitadas a 5MB e entradas para Desenvolvedores a 20MB. Ambas também exigem que cada borda tenha no máximo 4096 pixels, no máximo 1.000 quadros, e largura × altura × número de quadros no máximo 50.000.000. Uma animação curta, mas muito grande, pode atingir esses limites de segurança antes do limite de tamanho em bytes.

Repetindo solicitações sem trabalho duplicado

Escolha uma nova Idempotency-Key para cada nova solicitação de arquivo-e-opções e mantenha essa chave ao repetir após uma resposta de rede incerta. As chaves contêm 1–128 caracteres ASCII imprimíveis, sem espaços. Uma reprodução idêntica retorna a tarefa existente; alterar a entrada ou as opções sob a mesma chave retorna 409 IDEMPOTENCY_CONFLICT.

Para respostas 429 ou 503 temporárias, honre Retry-After quando presente e faça backoff. Uma escassez de créditos 402 precisa de uma redefinição de permissão ou mudança de plano; solicitações repetidas não resolverão. Um 503 FREE_COMPUTE_BUDGET_EXHAUSTED pausa novas tarefas gratuitas até a redefinição exibida, enquanto tarefas pagas e a ferramenta local do navegador permanecem separadas.

Uma tarefa com falha permanece a mesma tarefa com falha quando sua chave é reproduzida. Verifique a causa primeiro e use uma nova chave para uma nova tentativa deliberada. Não crie novas chaves a cada timeout: a primeira solicitação pode já ter sido aceita.

Pacotes de código aberto

Baixe o código-fonte do compressor autônomo para navegador e o pacote do código-fonte do adaptador MCP. Esses arquivos contêm o código de integração público, não código de conta, cobrança ou modelos privados.

Endpoints

OpenAPI JSON

Endpoints	Finalidade
POST /api/v1/compressions	Cria uma tarefa de compressão enviando um GIF ou uma URL HTTPS pública de GIF. A resposta é 202 com um id de tarefa; uma reprodução idempotente exata retorna a tarefa existente.
GET /api/v1/compressions/{id}	Lê o status da fila, custo em créditos, bytes de saída, targetMet, configurações aplicadas e result.downloadUrl quando o resultado está pronto.
GET /api/v1/usage	Lê o objeto usage encapsulado com active pool, limit, used, reserved, remaining, resetAt, windowStart e windowEnd.
POST /api/mcp	Endpoint MCP Streamable HTTP que expõe compress_gif, get_compression e get_usage com a mesma chave de API, créditos e limites de taxa que o REST.
GET /openapi.json	Contrato REST legível por máquina para clientes gerados, testes e ferramentas de IA.