# API para comprimir PDF: como chamar por HTTP com curl

A API do AjustaPDF comprime PDF com um POST em multipart, no campo file, sem chave. Veja o curl, os níveis, os limites do plano sem conta e os códigos de erro.

URL canônica: https://www.ajustapdf.com/blog/api-de-pdf-para-desenvolvedores

Publicado em 2026-10-03 · 5 min de leitura

A API do AjustaPDF recebe um PDF por POST em multipart, no campo file, no endereço https://api.ajustapdf.com/pdf/compress, com o nível no campo level (leve, media ou forte). A resposta é o próprio PDF comprimido, pronto para salvar. Não há chave de API: as chamadas usam a cota do plano sem conta, então ela serve para testes e uso leve.

## Primeira chamada com curl

O comando abaixo envia um arquivo, pede o nível médio e salva a resposta em outro arquivo. Use a opção -f: sem ela, uma resposta de erro em JSON também é gravada no arquivo de saída, e você pode achar que o PDF foi gerado:

```
curl -f -X POST https://api.ajustapdf.com/pdf/compress -F "file=@contrato.pdf" -F "level=media" -o contrato-comprimido.pdf
```

Para testar o fluxo, use um PDF pequeno, de uma ou duas páginas. Cada chamada conta na cota do dia, e um arquivo grande não mostra nada de novo sobre a integração. Quando o fluxo estiver certo, troque pelo arquivo real e confira o tamanho do resultado.

Com a opção -f, o curl sai com erro quando o servidor responde 4xx ou 5xx. Em scripts, isso é o que permite parar no primeiro arquivo que falhar.

## As operações disponíveis

Cada ferramenta do site tem um caminho próprio sob /pdf/. A tabela lista as dez operações. A especificação completa, com os campos de cada uma, está publicada em `https://www.ajustapdf.com/openapi.json`, no formato OpenAPI.

| Operação | Caminho | O que faz |
| --- | --- | --- |
| Comprimir | /pdf/compress | Reduz imagens nos níveis leve, media ou forte; devolve o original se não diminuir |
| Juntar | /pdf/merge | Concatena os PDFs na ordem enviada, sem recomprimir as páginas |
| Proteger | /pdf/encrypt | Criptografa com AES de 256 bits |
| Remover senha | /pdf/unlock | Abre com a senha informada e devolve a cópia sem criptografia |
| Dividir | /pdf/split | Extrai intervalos com a sintaxe 1-3,7,10-z ou separa cada página |
| Girar | /pdf/rotate | Gira páginas sem perda de qualidade |
| PDF para imagem | /pdf/pdf-to-images | Converte cada página em PNG ou JPEG, em um ZIP |
| Imagem para PDF | /pdf/images-to-pdf | Monta um PDF com uma imagem por página, sem recompressão |
| Organizar | /pdf/organize | Reordena, remove ou duplica páginas |
| Marca d'água | /pdf/watermark | Escreve um texto cinza na diagonal em todas as páginas |

## Campos e níveis de compressão

Na compressão, a API lê o arquivo do campo file e o nível do campo level. Se o campo não vier ou tiver outro valor, o servidor usa o nível médio. A tabela mostra o que cada nível faz por dentro, porque é isso que explica o tamanho do resultado:

| Valor de level | Imagens reamostradas para | Preset do Ghostscript |
| --- | --- | --- |
| leve | 300 DPI | /prepress |
| media (padrão) | 150 DPI | /ebook |
| forte | 72 DPI | /screen |

Texto e vetores não são reamostrados em nenhum dos níveis. Um PDF só de texto encolhe pouco, e a diferença entre os níveis aparece principalmente em fotos e páginas escaneadas.

## Limites e códigos de erro

O servidor aplica as mesmas regras de plano ao cliente da API. Sem conta, são 3 operações por dia, 25 MB por arquivo e 2 arquivos por operação. Com conta grátis, 10 por dia, 50 MB e 5 arquivos. Além da cota, há um teto de operações por IP, porque um laço sem controle de quem o executa pode esgotar o serviço para outras pessoas. Por isso, um servidor que faz muitas chamadas seguidas pode receber 429 mesmo sem ter esgotado a cota diária.

| Status | Código em error | Quando acontece |
| --- | --- | --- |
| 400 | NO_FILE | Nenhum arquivo chegou no campo file |
| 400 | INVALID_PDF | O arquivo não é um PDF válido |
| 402 | FILE_TOO_LARGE | Arquivo acima do tamanho do plano |
| 402 | TOO_MANY_FILES | Mais arquivos que o plano permite na mesma operação |
| 402 | QUOTA_EXCEEDED | O limite diário do plano já foi usado |
| 404 | UNKNOWN_OP | O caminho não corresponde a nenhuma operação |
| 429 | TOO_MANY_REQUESTS | Muitas operações vindas da mesma rede no dia |
| 504 | TIMEOUT | O processamento passou do tempo máximo |

Em respostas bem-sucedidas, os cabeçalhos x-quota-used e x-quota-limit mostram quantas operações já foram usadas e o limite do dia. Use-os para mostrar o consumo ao usuário sem fazer uma chamada extra.

## Consultar a cota antes de enviar

Antes de montar um lote, consulte o plano e o uso atual com um GET em /pdf/limits. A resposta traz o plano de quem chama (tier), as operações usadas e o limite do dia, além do tamanho máximo por arquivo e o número máximo de arquivos. Com isso, seu código sabe quantas operações ainda cabem antes de começar:

```
curl https://api.ajustapdf.com/pdf/limits
```

A consulta não gasta operação. Ela é útil para mostrar ao usuário quanto falta para o limite do dia, em vez de descobrir isso pelo erro 402.

## Fluxo recomendado no seu código

1.  Verifique o tamanho e a quantidade de arquivos antes de enviar. Recusar no seu código um arquivo acima do limite economiza uma chamada que o servidor responderia com 402.
2.  Envie a requisição com multipart/form-data e o campo file. Não defina o Content-Type à mão: a biblioteca HTTP monta o limite do multipart sozinha.
3.  Em 200, compare o tamanho do corpo com o do arquivo enviado. Se for igual, a compressão não reduziu nada, e você pode informar isso ao usuário.
4.  Em 402 com QUOTA\_EXCEEDED ou em 429, não repita a chamada em laço. Espere e mostre a mensagem ao usuário.
5.  Não guarde o PDF de saída por mais tempo do que o necessário. O servidor já apagou o seu arquivo quando a resposta saiu, e a cópia do seu sistema é de sua responsabilidade.

## Quando a API não serve

A API é útil para integrar uma etapa de compressão a um fluxo pequeno, para testes e para protótipos. Ela não é o caminho para processar milhares de documentos por dia: não há chave, contrato de volume nem cota comprada por integração. Se o seu sistema precisa desse volume, o caminho é rodar o Ghostscript e o qpdf na sua própria infraestrutura, como mostra o [guia de compressão no terminal](/blog/comprimir-pdf-ghostscript-qpdf).

Há também o tema de dados pessoais. Quando o PDF tem CPF, endereço ou dados de clientes, ele sai do seu sistema e chega ao servidor. Antes de integrar, leia o [guia sobre LGPD e envio de documentos de clientes](/blog/lgpd-enviar-documento-de-cliente-site) e defina se o fluxo pode mesmo sair da sua rede.

Para a operação de compressão no site, a mesma lógica está na [ferramenta de comprimir PDF](/comprimir-pdf). A API faz o mesmo processamento, sem a tela.

## Perguntas frequentes

### Qual é o endereço da API para comprimir PDF?

É um POST para https://api.ajustapdf.com/pdf/compress, em multipart/form-data. O PDF vai no campo file e, opcionalmente, o nível vai no campo level, com os valores leve, media ou forte. A resposta é o próprio PDF comprimido.

### A API do AjustaPDF precisa de chave?

Não. As chamadas não usam chave de API e contam na cota do plano sem conta: 3 operações por dia, arquivos de até 25 MB e 2 arquivos por operação. Ela serve para testes e uso leve. Não há plano de volume pela API: para escala, o caminho é rodar o processamento na sua infraestrutura.

### O que a API devolve quando o arquivo não diminui?

O PDF original, sem alteração. O servidor só entrega a versão comprimida quando ela é menor. Por isso, compare o tamanho da resposta com o do arquivo enviado antes de mostrar o resultado ao usuário.

### Qual código de erro aparece quando o limite diário acaba?

O código é 402, com o campo error igual a QUOTA_EXCEEDED. A resposta traz também o uso atual e o limite do plano. Não insista com repetições: a cota é diária, então insistir no mesmo dia não resolve.

### Dá para usar a API para juntar PDFs de clientes?

Tecnicamente, sim, pela operação merge. Mas o arquivo sai do seu sistema e vai ao servidor, e a cota sem conta é pequena. Para dados pessoais, avalie uma execução local com qpdf, que faz a junção sem enviar nada para fora.