Comprimir e juntar PDF pelo terminal com curl

Para comprimir ou juntar PDFs pelo terminal, crie uma chave de API na sua conta e faça um POST multipart para a rota da operação, com o cabeçalho Authorization no formato Bearer. Um comando devolve o arquivo comprimido ou unido. Use a opção -f, para que o curl falhe quando a API recusa o pedido, e um erro nunca vire um arquivo .pdf corrompido.

Crie a chave e guarde-a fora do histórico

Entre na sua conta e abra a seção Chaves de API. Dê um nome que diga onde a chave vai ser usada, como “notebook pessoal” ou “script de contratos”. Ela começa com apdf_live_ e é mostrada uma única vez. O servidor guarda só o hash dela, então, se você perder a chave, a saída é criar outra e revogar a antiga. Cada conta tem até cinco chaves ativas.

Escrever a chave no comando a deixa no histórico do terminal. Peça-a com o comando read, que não mostra o que você cola, e exporte a variável só na sessão. Em scripts recorrentes, prefira um arquivo de ambiente com permissão restrita a você (em Python, a chave vem de uma variável de ambiente, como em chamar a API do AjustaPDF com Python).

read -s AJUSTAPDF_KEY
export AJUSTAPDF_KEY

No Windows, o PowerShell tem o curl.exe, que aceita os mesmos comandos deste guia; o guia de juntar PDFs de várias pastas com PowerShell mostra a variável de ambiente por lá.

Comprimir um arquivo

A rota /pdf/compress recebe um arquivo no campo file e o nível no campo level. Os níveis são leve, media (sem acento), forte e alvo. O nível alvo usa o campo targetMb, com o tamanho máximo em megabytes, de 0,05 a 200: o servidor tenta leve, depois média e depois forte, cada uma a partir do original, e devolve a primeira que couber. Um exemplo com o nível médio:

curl -f -sS -X POST https://api.ajustapdf.com/pdf/compress \
  -H "Authorization: Bearer $AJUSTAPDF_KEY" \
  -F "file=@contrato.pdf" \
  -F "level=media" \
  -o contrato-medio.pdf

A opção -o grava a resposta no arquivo de saída. Se a API recusar o pedido, ela devolve um JSON com os campos error e message. Sem o -f, esse JSON iria para o arquivo de saída com cara de PDF; com o -f, o curl sai com código 22 e não grava o corpo do erro. O -sS esconde a barra de progresso, mas mantém a mensagem de erro do próprio curl.

Para comprimir até um tamanho, troque o nível por alvo e peça os cabeçalhos com -D. Se nem o nível forte couber no tamanho pedido, o arquivo volta mesmo assim, o menor que saiu, e o cabeçalho x-compress-fitted vem com 0.

curl -f -sS -D - -X POST https://api.ajustapdf.com/pdf/compress \
  -H "Authorization: Bearer $AJUSTAPDF_KEY" \
  -F "file=@relatorio.pdf" \
  -F "level=alvo" -F "targetMb=2" \
  -o relatorio-2mb.pdf

O guia sobre texto borrado depois de comprimir ajuda a decidir o nível quando o arquivo é uma digitalização.

Juntar arquivos na ordem certa

A rota /pdf/merge recebe o campo files repetido, uma vez por arquivo, e exige pelo menos dois. A ordem em que você escreve os campos é a ordem das páginas no resultado. Sem rede, o mesmo trabalho sai com o pdftk, no próprio computador.

curl -f -sS -X POST https://api.ajustapdf.com/pdf/merge \
  -H "Authorization: Bearer $AJUSTAPDF_KEY" \
  -F "files=@01-capa.pdf" \
  -F "files=@02-miolo.pdf" \
  -F "files=@03-anexos.pdf" \
  -o relatorio-unido.pdf

Antes de automatizar, faça o teste com dois arquivos pequenos e abra o resultado. O juntar copia as páginas sem reprocessar, então texto e imagens ficam como estavam. Anotações e campos de formulário vêm junto; marcadores, camadas, rótulos e metadados do documento de origem não entram no resultado, como a ferramenta de juntar PDF descreve. O guia links e sumário ao juntar PDF mostra o que sobrevive.

Ler a cota e os erros

Para saber quanto resta, grave os cabeçalhos da resposta com -D e leia x-quota-used e x-quota-limit: as operações já usadas no dia e o teto do plano. Eles aparecem nas respostas bem-sucedidas. Um script que lê esses números depois de cada envio para antes de bater no teto, em vez de descobrir o bloqueio pelo erro 402.

Para ler a mensagem de um erro sem arriscar um arquivo falso, guarde o código HTTP com -w e só mantenha o arquivo quando o código for 200:

status=$(curl -sS -o saida.pdf -w "%{http_code}" -X POST https://api.ajustapdf.com/pdf/compress \
  -H "Authorization: Bearer $AJUSTAPDF_KEY" -F "file=@contrato.pdf" -F "level=media")
if [ "$status" != "200" ]; then cat saida.pdf; echo; rm saida.pdf; fi

Quando o terminal não é o caminho

Uma chamada por arquivo é simples, mas não substitui um fluxo com centenas de documentos. Para processar uma pasta inteira, veja o guia de processar uma pasta de PDFs, que mostra os limites de cada plano. Se você não quer enviar os arquivos para servidor nenhum, o caminho é o Ghostscript e o qpdf instalados na sua máquina, e o guia de comprimir com Ghostscript mostra esse passo a passo. Para uso pontual, não precisa de chave nem de terminal: envie o arquivo em comprimir PDF e escolha o nível na tela.

A lista completa de rotas, campos e erros está na referência da API para desenvolvedores. Se quem vai usar as ferramentas é um assistente de IA, a mesma chave serve no servidor MCP em https://api.ajustapdf.com/mcp, que gasta a mesma cota. No Claude Code (a leitura de PDF por ele tem um guia próprio, ler PDF no Claude Code):

claude mcp add --transport http ajustapdf https://api.ajustapdf.com/mcp \
  --header "Authorization: Bearer apdf_live_..."

Checklist antes de rodar em lote

• Teste com um arquivo pequeno e abra o resultado antes de repetir.
• Use a opção -f e grave o resultado num nome novo, para não sobrescrever o original.
• Guarde os cabeçalhos da resposta para acompanhar a cota.
• Revogue a chave se ela sair do seu computador, como num repositório.