# Comprimir e juntar PDF pelo terminal com curl

Como comprimir e juntar PDFs com curl e uma chave de API: a chave fora do histórico, a ordem dos arquivos, a cota nos cabeçalhos e os códigos de erro.

URL canônica: https://ajustapdf.com/blog/curl-api-pdf-terminal

Publicado em 2026-10-20 · 5 min de leitura · por [AjustaPDF](https://ajustapdf.com/sobre#editorial)

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](/blog/pdf-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](/blog/pdf-ficou-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](/juntar-pdf) descreve. O guia [links e sumário ao juntar PDF](/blog/links-e-sumario-sobrevivem-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
```

| Código e error | Sentido | O que fazer |
| --- | --- | --- |
| 400 NO_FILE | Nenhum arquivo no campo file ou files | Confira o nome do campo e o caminho depois do @ |
| 400 INVALID_PDF ou PASSWORD_REQUIRED | O arquivo não é um PDF válido ou tem senha | Confira o arquivo; desbloqueie antes se souber a senha |
| 401 INVALID_API_KEY | Chave errada ou revogada | Confira a variável ou crie outra chave |
| 402 QUOTA_EXCEEDED | Operações do dia acabaram | Espere a virada do dia ou troque de plano |
| 402 FILE_TOO_LARGE | Arquivo acima do limite do plano | Divida o arquivo ou comprima antes |
| 402 TOO_MANY_FILES | Mais arquivos que o plano aceita numa operação | Junte em grupos menores |
| 429 TOO_MANY_REQUESTS | Muitas operações vindas da mesma rede | Espere e tente de novo mais tarde |
| 504 TIMEOUT | O processamento passou do tempo permitido | Tente de novo com um arquivo menor |

## 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](/blog/pdf-em-lote-pasta-inteira), 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](/blog/comprimir-pdf-ghostscript-qpdf) mostra esse passo a passo. Para uso pontual, não precisa de chave nem de terminal: envie o arquivo em [comprimir PDF](/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](/blog/api-de-pdf-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.

## Perguntas frequentes

### Como comprimir um PDF pelo terminal com curl?

Crie uma chave de API na sua conta, guarde-a numa variável de ambiente e envie o arquivo com um POST multipart para https://api.ajustapdf.com/pdf/compress, com o arquivo no campo file e o nível no campo level. Grave o resultado com -o e use -f para o curl falhar quando a API responder com erro, em vez de gravar um JSON de erro como se fosse PDF.

### Como juntar vários PDFs com curl numa única chamada?

Repita o campo files para cada arquivo, na ordem em que as páginas devem aparecer: -F “files=@parte1.pdf” -F “files=@parte2.pdf”. A rota /pdf/merge devolve um único PDF e exige pelo menos dois arquivos. O plano define quantos arquivos cabem numa operação, e acima desse número a API recusa o envio com TOO_MANY_FILES.

### Dá para chamar a API com curl sem criar uma chave?

Dá, com os limites do plano sem conta: 3 operações por dia, arquivos de até 25 MB e 2 arquivos por operação. Sem chave, a API conta o uso por um cookie chamado apdf_device, então use -c e -b com um arquivo de cookies para o curl reaproveitá-lo entre as chamadas. Para uma rotina, a chave é o caminho certo.

### Quanto de cota a chamada pelo curl gasta?

Cada chamada bem-sucedida gasta uma operação da cota da conta dona da chave, a mesma que o site usa. Para saber quanto sobrou, leia os cabeçalhos de resposta x-quota-used e x-quota-limit, que o curl mostra com a opção -D. Uma chamada recusada por erro de chave, de tamanho ou de cota não gasta operação.