Docs para desenvolvedores

Início rápido

Comprima sua primeira imagem em 30 segundos: crie uma chave de API no console e, depois, envie uma requisição.

O resultado é retornado por um link privado criptografado que só você, o detentor da chave, pode acessar — as imagens são usadas apenas para esta compressão, criptografadas o tempo todo, nunca vazadas e nunca usadas para treinamento ou qualquer outra finalidade.

Autenticação

• HTTP Basic (compatível com APIs de compressão populares): usuário fixo em api, senha é a sua chave de API — Authorization: Basic base64("api:KEY")
• Bearer (recomendado para a camada nativa): Authorization: Bearer KEY

Os prefixos de chave são mp_live_ (produção) e mp_test_ (sandbox); o servidor armazena apenas um hash da chave, e a chave completa é exibida apenas uma vez na criação. Cada conta pode ter até 5 chaves. Falhas de autenticação sempre retornam 401 sem distinguir a causa (para evitar enumeração).

POST /shrink Comprimir uma imagem

O corpo da requisição é uma de duas opções: uma imagem em binário bruto (PNG / JPEG / WebP / HEIC / GIF / BMP / TIFF / AVIF) ou um JSON especificando uma URL de origem (apenas endereços públicos http/https, com tempo limite de busca de 10 segundos). Quando nenhum formato de saída é especificado, o formato original é mantido: PNG / JPEG / WebP / GIF / TIFF / AVIF são gerados em seu formato original (AVIF→AVIF, TIFF→TIFF); HEIC é convertido para JPEG; BMP, que não pode ser comprimido em seu próprio formato, é convertido para PNG. O GIF é otimizado sem perdas por padrão (continua GIF) e também pode ser convertido para WebP para economizar mais.

Em caso de sucesso, retorna 201 Created, com cabeçalhos de resposta incluindo Location (o endereço do resultado) e Compression-Count (imagens cobradas neste mês):

GET /output/{id} Baixar o resultado

Exige autenticação; retorna o binário do resultado comprimido. Os resultados são servidos por um link privado criptografado; quando o link expira, retorna 404 OutputExpired, e você pode comprimir novamente para obtê-lo de novo. Baixar novamente o mesmo resultado não é cobrado.

POST /output/{id} Operações derivadas

Execute resize / convert / preserve em um resultado comprimido; cada saída derivada conta como 1 imagem:

• resize.method: scale (proporcional por um lado) / fit (cabe inteiro) / cover (recorta para preencher, atualmente recorte central)
• convert.type: converte entre image/webp, image/png e image/jpeg
• preserve: mantém os metadados de copyright / creation / location

POST /v1/compress Compressão síncrona (camada nativa)

Uma única requisição retorna o binário do resultado comprimido diretamente, economizando uma ida e volta — prático para CI:

• quality: smart (padrão) / high / extreme / 1-100
• format: keep (manter o formato original) / webp
• Cabeçalhos de resposta: X-Input-Size / X-Output-Size / X-Ratio / Compression-Count

GET /v1/usage Consulta de uso

Retorna a contagem deste mês, a cota gratuita restante e o saldo restante dos pacotes de crédito — idêntico ao console:

Cotas e limites de taxa

• Taxa: 10 req/s por chave, burst de 20 (token bucket); ao ultrapassar, retorna 429 + Retry-After
• Concorrência: tarefas em andamento por chave <= 20
• Cota mensal gratuita: 500 imagens/mês/conta; quando esgotada sem pagamento cadastrado, retorna 429 AccountLimitReached
• Por arquivo: 5 MB grátis; 80 MB pago; personalizável para empresas
• Pixels: <= 100 megapixels; ao ultrapassar, retorna 422 ImageTooComplex

Cabeçalhos de resposta em todos os endpoints tarifados: Compression-Count, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Cobrança

• POST /shrink com sucesso (201): conta como 1 imagem
• POST /v1/compress com sucesso (200): conta como 1 imagem
• GET /output/{id} baixar novamente: não é cobrado
• POST /output/{id} operação derivada com sucesso: conta como 1 imagem a cada vez
• 4xx / 5xx, bloqueios da triagem de conteúdo e falhas de busca de URL: não são cobrados; em uma nova tentativa bem-sucedida, conta apenas a chamada que teve sucesso

Ordem de dedução: cota mensal do plano → pacotes de crédito (primeiro comprado, primeiro usado, nunca expiram). Pré-pago, sem fatura mensal por uso — quando a cota acaba, pausa, e comprar um pacote de crédito a restaura.

Integração de IA / Skill

O MiniPic oferece uma Agent Skill oficial (minipic-compress): uma vez instalada, diga a qualquer agente de IA que suporte o padrão aberto Anthropic Agent Skills (Claude Code / Cursor / Codex CLI / Copilot CLI, etc.) algo como "comprima as imagens desta pasta" e ele chamará automaticamente a API do MiniPic para comprimir, converter para WebP, processar em lote e reportar a taxa de compressão — sem precisar escrever curl ou lógica de repetição à mão.

Instalar

Escolha uma das opções a seguir (três opções):

Para outros agentes que suportem o padrão Agent Skills (Cursor / Codex CLI / Copilot CLI, etc.), siga a documentação deles para colocar o diretório minipic-compress/ no caminho de skills correspondente.

Configure sua chave de API

A chave é lida apenas de uma variável de ambiente e nunca é codificada de forma fixa ou exibida. Depois de criar uma chave no console, defina-a no seu ambiente:

Escopo e exemplos de acionamento

A Skill é acionada automaticamente quando você expressa intenções como:

• "Comprima esta imagem / as imagens desta pasta"
• "Converta hero.png para WebP e deixe o menor possível"
• "Estas imagens estão muito grandes — otimize-as em lote antes de empacotar e me diga quanto economizei"

Capacidades: compressão de arquivo único / lote de pasta / URL remota, conversão entre PNG·JPEG·WebP·GIF, seleção de predefinição de qualidade (smart / high / extreme), cálculo e relatório automáticos da porcentagem de economia, e nova tentativa automática com back-off no limite de taxa 429.

Extensão do VS Code

A extensão oficial MiniPic Image Compression permite comprimir imagens do workspace diretamente no seu editor, sem escrever curl à mão, com a tecnologia do motor próprio do MiniPic. Ela suporta PNG / JPEG / WebP / GIF / AVIF / TIFF e pode converter o formato durante a compressão (como para WebP / AVIF para economizar mais), e funciona no VS Code, no Cursor e em outros editores compatíveis.

Instalar

Escolha uma das opções a seguir:

• No painel de Extensões do VS Code (⇧⌘X), pesquise MiniPic e clique em Instalar;
• ou execute ext install minipic.minipic-vscode na paleta de comandos;
• ou acesse a página da extensão no Visual Studio Marketplace e clique em Instalar.

Configure sua chave de API

Depois de criar uma chave (começando com mp_live_) no console, execute MiniPic: Set API Key na paleta de comandos (⇧⌘P) e cole-a. A chave é armazenada com segurança no SecretStorage do VS Code e nunca é gravada em configuração de texto puro nem sincronizada via settings.json.

Como usar

• Comprimir pelo botão direito: selecione imagens ou pastas no Explorer (única, multisseleção ou diretório inteiro recursivamente) → clique com o botão direito em MiniPic: Compress Images para comprimir no lugar usando as configurações atuais de qualidade e formato.
• Converter para WebP e atualizar referências: clique com o botão direito em MiniPic: Convert to WebP and Update References para converter para WebP enquanto atualiza automaticamente as referências a essa imagem em todo o workspace.
• Compressão automática: quando ativada, monitora imagens novas/alteradas do workspace e as comprime automaticamente (desativada por padrão, pois consome cota); alterne pela barra de status ou com MiniPic: Toggle Auto-Compress.
• Ver uso: execute MiniPic: View Usage para ver a contagem comprimida deste mês, o saldo gratuito e a estimativa de uso — idêntico ao console.

Configurações comuns

Códigos de erro

O corpo do erro segue a convenção das APIs de compressão populares: {"error": "code", "message": "descrição legível por humanos"}; campos só são adicionados, nunca removidos.