Documentação API e MCP

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

Crie uma chave de API na página de configurações da conta depois da ativação. Todas as chaves da conta compartilham o mesmo pool de créditos, limites de velocidade e limites de trabalhos inacabados. Quando o orçamento de computação gratuita se esgota, novos trabalhos gratuitos pausam até o horário de reinício exibido; trabalhos pagos do Developer e a compactação local no navegador continuam separados.

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

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

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 fica dentro de uma propriedade job. A resposta de criação sozinha não contém link de download. Consulte o endpoint de status mesmo quando a criação repetir um trabalho já concluído. Substitua YOUR_JOB_ID no exemplo por esse id, depois copie result.downloadUrl de uma resposta succeeded para DOWNLOAD_URL antes de executar o comando de download.

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

Consulte a cada poucos segundos e fique dentro do limite de leitura da conta. Uma nova consulta de status pode renovar um link de download expirado enquanto o arquivo ainda estiver acessível. Links duram até 15 minutos e nunca estendem o acesso ao arquivo além de 24 horas. Consultar, baixar e repetir exatamente a solicitação idempotente não gastam créditos.

Solicitações JSON de criação 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 dos uploads.

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

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

Janelas Free API reiniciam por mês calendário UTC. Janelas Developer reiniciam mensalmente na âncora da assinatura, inclusive assinaturas anuais. Créditos não acumulam. Contas Free podem ter 2 trabalhos inacabados, contas Developer podem ter 20, e a fila gratuita pode conter 100 trabalhos. Um trabalho gratuito aguardando mais de 10 minutos é encerrado e libera sua reserva.

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

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

Chame compress_gif com sourceUrl, um objeto options opcional e um idempotencyKey obrigatório. Depois passe o id retornado para get_compression. O adaptador envolve a resposta REST em structuredContent.data; transporte de ferramenta bem-sucedido não significa que o trabalho de compactação terminou. Use get_usage com um objeto vazio para consultar seu saldo.

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

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

Os campos credits e cost.credits do trabalho mostram o custo cotado, não prova de débito concluído. Créditos são reservados quando um trabalho é aceito, liquidados no sucesso e liberados na falha. Consulte /api/v1/usage para ver o saldo atual usado, reservado e restante.

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 API ausentes ou inválidas. 402 é apenas para créditos de usuário esgotados. 403 cobre acesso Free API inativo. 409 cobre conflitos de idempotência. 413 cobre limites de tamanho de entrada na nuvem. 422 cobre dados GIF ou opções inválidos. 429 cobre limites de criação/leitura e limites de trabalhos inacabados. 503 cobre pressão temporária de fila ou FREE_COMPUTE_BUDGET_EXHAUSTED; respeite Retry-After quando presente.

Compactação local no navegador e trabalhos de API na nuvem têm fluxos de dados diferentes. Escolha a ferramenta do navegador quando o GIF precisar ficar no seu dispositivo; use REST ou MCP quando um fluxo remoto precisar processá-lo.

A ferramenta do navegador não envia seu GIF. Importar uma URL contata diretamente o site que hospeda aquela imagem. Solicitações API e MCP enviam um arquivo ou pedem que nosso serviço busque uma URL HTTPS pública. A Cloudflare hospeda a aplicação, banco de dados e armazenamento de arquivos. O acesso aos arquivos de entrada e saída da API expira após 24 horas; links de download duram até 15 minutos. A limpeza em segundo plano remove arquivos expirados, então a exclusão física pode acontecer depois. Registramos eventos técnicos de uso, como sucesso ou falha de compactação, tamanho de entrada e saída, status do alvo e downloads em logs de serviço da Cloudflare para medir confiabilidade e uso. Esses eventos excluem nomes de arquivo, URLs de origem e conteúdo dos arquivos. A Cloudflare também processa dados de solicitação para entregar e proteger o serviço. Logs de eventos de produto são retidos por até 7 dias.

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 API. Todas as chaves de uma conta compartilham franquias e limites.

Mantenha a chave em uma variável de ambiente do 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 chaves API e crie uma substituta. A ferramenta gratuita do navegador não precisa de chave API.

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

colors opcional 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 para manter as dimensões originais. Nenhuma opção de remover quadros ou converter formato é compatível.

Uma solicitação processa um GIF. Entradas Free API são limitadas a 5MB e entradas Developer a 20MB. Ambas também exigem cada borda com no máximo 4096 pixels, no máximo 1.000 quadros e width × height × frame count de no máximo 50.000.000. Uma animação curta, mas muito grande, pode atingir esses limites de segurança antes do limite em bytes.

Escolha um novo Idempotency-Key para cada nova solicitação de arquivo e opções e mantenha essa chave ao tentar novamente depois de uma resposta de rede incerta. Chaves contêm 1 a 128 caracteres ASCII imprimíveis, sem espaços. Uma repetição idêntica retorna a tarefa existente; mudar a entrada ou opções sob a mesma chave retorna 409 IDEMPOTENCY_CONFLICT.

Para respostas 429 ou 503 temporárias, respeite Retry-After quando presente e faça backoff. Uma falta de créditos 402 precisa de reinício de franquia ou mudança de plano; repetir solicitações não resolverá. Um 503 FREE_COMPUTE_BUDGET_EXHAUSTED pausa novos trabalhos gratuitos até o reinício exibido, enquanto trabalhos pagos e a ferramenta local do navegador permanecem separados.

Um trabalho com falha continua sendo o mesmo trabalho com falha quando sua chave é repetida. Verifique a causa primeiro, depois 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.