Sem login: como o limite anônimo mantém a ferramenta gratuita

O PDF123 mantém um caminho de envio e download sem conta. As mesmas operações também ficam sob /api/v1/, para que um script as chame sem ninguém clicar em Process. O uso anônimo não exige chave de API. Os limites de requisição evitam que essa superfície vire um serviço gratuito sem teto.

O anônimo é o caminho padrão

Solte um arquivo numa página de ferramenta como Comprimir ou Mesclar e execute. O REST anônimo sob /api/v1/ funciona do mesmo jeito para as ferramentas do catálogo. Os endpoints sob /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ e /api/v1/filter/ são os prefixos anônimos das ferramentas; cada ferramenta do portal corresponde a um caminho dentro deles.

O login existe para você criar uma chave de API pessoal para automação, não para transformar o botão Process num paywall. O formulário do navegador e o contrato HTTP continuam alinhados: o bloco "Call this from code" de cada ferramenta monta um curl com os mesmos campos que o formulário envia.

Rotas de administração, de perfil de usuário e outras que não são ferramentas ficam fora desses prefixos. Quem chama uma rota protegida de forma anônima recebe uma falha de autenticação, não um passe livre por toda a superfície da API.

O que os cabeçalhos informam

Toda resposta da API hospedada anuncia o orçamento (implementado no pdfx-server):

• X-RateLimit-Limit: teto do período anunciado naquela resposta
• X-RateLimit-Remaining: orçamento restante no período atual
• X-RateLimit-Reset: marcador de reinício da janela (leia o valor; não presuma um dia de calendário)

Em HTTP 429, o Retry-After diz a um cliente educado quando tentar de novo. As falhas de cota usam o código de problema estruturado rate_limited em Erros para desenvolvedores, com o mesmo formato application/problem+json das outras falhas da API. Assim um script decide pelo código, sem raspar uma página de erro em HTML.

Os tetos numéricos mudam conforme as configurações de implantação. Os cabeçalhos de uma resposta concreta são a fonte da verdade, não um retrato congelado neste texto. Um cliente que fixar no código o número diário lido aqui vai errar na próxima vez que um operador reajustar o período. Prefira ler X-RateLimit-Remaining depois de cada chamada e recuar quando ele se aproximar de zero.

Por que uma ferramenta gratuita ainda limita quem chama

Sem tetos, os endpoints anônimos viram a fazenda de processamento em lote de outra pessoa. Os limites mantêm as tarefas pontuais viáveis enquanto cargas mais pesadas ou privadas migram para chaves ou para self-host.

Os tetos também protegem a CPU compartilhada nas operações realmente caras: mesclagens grandes, o OCR que devolve Markdown a partir de digitalizações (text/markdown, não um PDF com camada refeita) e execuções de várias etapas em POST /api/v1/pipeline. A escolha de produto é "anônimo e finito", não "anônimo e ilimitado".

O acesso anônimo continua sendo processamento temporário: os uploads são tratados para a tarefa e limpos quando o resultado fica pronto. O limite de requisições trata da divisão justa de capacidade, não de inventar um repositório de documentos de longo prazo atrás de um login gratuito.

As chaves mudam a identidade, não o catálogo

Crie uma chave em Desenvolvedores quando precisar de identidade estável para quem chama, de novas tentativas com Idempotency-Key que não podem executar o trabalho duas vezes, ou de um servidor self-hosted com chave global fixa (SECURITY_CUSTOMGLOBALAPIKEY na sua máquina). A OpenAPI continua em /v1/openapi.json, na URL base que você usar.

O MCP em /mcp segue o mesmo catálogo e a mesma lógica de chave para clientes de automação. As operações continuam iguais, seja quem chama anônimo ou identificado. O que muda é a autenticação e a cota.

Para as quatro formas de acessar uma mesma operação (navegador, curl, MCP, CLI), veja A mesma operação em quatro clientes. Para levar a superfície inteira para a sua rede quando os tetos ou a retenção não bastarem, veja O que o self-host realmente traz.