Como usar o PDF123 a partir do código?
As quatro interfaces chamam as mesmas operações, então juntar arquivos dá o mesmo resultado em todas. Escolha conforme o lugar onde seu código roda.
| Interface | Ideal para | Instalação ou endereço | Guia |
|---|---|---|---|
| API REST | Qualquer linguagem, servidores, scripts de shell | https://pdf123.xyz/api/v1 | Referência da API |
| SDK TypeScript | Código Node, Bun e de navegador que precisa de tipos | npm install @pdf123/sdk | Guia do SDK |
| Linha de comando | Terminais, tarefas de CI, lotes de arquivos locais | npm install -g @pdf123/cli | Guia da CLI |
| MCP | Agentes de IA como Claude Code, Claude Desktop e Cursor | npx -y @pdf123/mcp ou https://pdf123.xyz/mcp | Guia do MCP |
Use a API REST se o seu código não for escrito em TypeScript. Use o SDK se for, porque as opções das ferramentas são tipadas e verificadas antes do envio. Use a linha de comando para tarefas pontuais e scripts de shell. Use o MCP quando um agente de IA deve decidir qual ferramenta executar.
O catálogo tem 97 ferramentas. 58 delas têm uma página neste site, como Juntar PDF, Dividir PDF e Comprimir PDF. As demais são operações do backend sem página web, e todas estão disponíveis no SDK, na linha de comando e no MCP.
Como faço a primeira requisição?
Junte dois arquivos com curl. A requisição é um formulário multipart com uma parte fileInput por arquivo.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfA mesma junção com o SDK TypeScript:
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";
const client = new Pdf123Client();
const result = await client.run("merge", {
input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });A mesma junção com a linha de comando:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfComo funciona a autenticação?
Chamadas anônimas à API pública não exigem conta nem chave. Envie uma chave de API no cabeçalho X-API-KEY quando quiser identificar seu tráfego ou chamar o endpoint MCP hospedado, que sempre exige chave.
Entre para criar uma chave no painel abaixo e guarde-a em um lugar seguro.
Verificando sua sessão…
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-H "X-API-KEY: <your-key>" \
-F [email protected] -F [email protected] -o merged.pdfO SDK recebe a chave como apiKey. A linha de comando e o servidor MCP local a leem da variável de ambiente PDFX_API_KEY.
Nota
Em um servidor próprio, defina a variável de ambiente SECURITY_CUSTOMGLOBALAPIKEY para definir uma chave que o servidor aceita. Veja Self-host.
Onde fica a referência da API?
A API REST está documentada de duas formas. O Swagger UI permite testar cada endpoint no navegador. O documento OpenAPI é a fonte legível por máquina para geradores de clientes.
Toda operação é um POST sob a URL base https://pdf123.xyz/api/v1, agrupada por categoria. Por exemplo, juntar é /general/merge-pdfs e comprimir é /misc/compress-pdf.
Como encadeio várias ferramentas em uma requisição?
POST /api/v1/pipeline recebe as partes fileInput e um campo steps. O campo steps é um array JSON de objetos com op e, opcionalmente, params. Cada etapa recebe a saída da etapa anterior.
curl -X POST https://pdf123.xyz/api/v1/pipeline \
-F [email protected] -F [email protected] \
-F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
-o out.pdfComo repito uma requisição com segurança?
Envie o cabeçalho Idempotency-Key em qualquer operação. Uma repetição da mesma requisição em até 24 horas devolve o primeiro resultado com o cabeçalho Idempotency-Replayed: true, em vez de executar de novo. Usar a mesma chave para uma requisição diferente é rejeitado. Resultados maiores que 32 MiB não são armazenados, então repetir uma requisição assim responde 409 e exige uma chave nova.
Quais são os limites de tamanho e de taxa?
| Limite | Valor |
|---|---|
| Tamanho de arquivo no site | 500 MB por arquivo |
| Corpo de uma requisição direta à API | 100 MiB, incluindo a estrutura multipart |
| Envio em partes | O SDK passa automaticamente para a API de upload acima de 95 MB no total |
As respostas trazem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta com status 429 acrescenta Retry-After. Leia os cabeçalhos em vez de supor uma cota fixa, pois um servidor próprio define seus próprios limites. O artigo do blog sobre o limite de tamanho da requisição explica o erro que você recebe quando o corpo é grande demais.
Como é um erro?
As falhas devolvem application/problem+json com os campos type, title, status, detail, code, reason e hint. Ramifique a lógica por reason e use code como alternativa. O texto de detail é escrito para pessoas e nunca contém a saída bruta da ferramenta. Todos os códigos estão em Códigos de erro.
| Código ou motivo | Status HTTP | Significado |
|---|---|---|
bad_request | 400 | Parâmetros ou corpo multipart inválidos |
password_required | 400 | O PDF está criptografado e nenhuma senha foi enviada |
invalid_pdf | 400 | O arquivo não é um PDF ou está danificado; tente Reparar PDF |
page_out_of_range | 400 | Uma página solicitada não existe |
not_found | 404 | Caminho de operação desconhecido |
rate_limited | 429 | Cota esgotada; aguarde o tempo de Retry-After |
Quais ferramentas posso chamar primeiro?
Estas doze ferramentas cobrem a maioria das requisições. Use a página da ferramenta para testá-la no navegador.
| Página da ferramenta | Endpoint da API | Comando da CLI | O que faz |
|---|---|---|---|
| Juntar | /general/merge-pdfs | pdfx merge | Combina vários PDFs em um só |
| Dividir | /general/split-pages | pdfx split | Divide um PDF em arquivos separados |
| Comprimir | /misc/compress-pdf | pdfx compress | Recomprime os fluxos do PDF para reduzir o tamanho |
| Girar | /general/rotate-pdf | pdfx rotate | Muda a orientação das páginas |
| Proteger | /security/add-password | pdfx protect | Criptografa um PDF com senha |
| Desbloquear | /security/remove-password | pdfx unlock | Remove a proteção por senha |
| Marca d'água | /security/add-watermark | pdfx watermark | Adiciona uma marca d'água de texto ou imagem |
| OCR | /misc/ocr-pdf | pdfx ocr | Lê um PDF digitalizado e devolve Markdown |
| PDF para Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Converte um PDF em Markdown |
| PDF para Word | /convert/pdf/word | pdfx convert-to-word | Converte um PDF em um arquivo Word editável |
| Informações do documento | /security/get-info-on-pdf | pdfx get-info | Informa metadados, permissões, fontes e estrutura |
| Reparar | /misc/repair | pdfx repair | Reconstrói a estrutura de um PDF danificado |
Os endpoints são relativos a https://pdf123.xyz/api/v1. Execute pdfx list ou abra o documento OpenAPI para ver as 97 ferramentas.
Como uso o PDF123 a partir de um agente de IA?
Um agente pode usar as ferramentas de três maneiras:
- Conecte um servidor MCP. O guia do MCP cobre o servidor local
@pdf123/mcp, para arquivos na sua máquina, e o endpoint hospedado emhttps://pdf123.xyz/mcp. - Carregue uma skill de agente. Skills para agentes são arquivos
SKILL.mdpara Claude Code, Codex, Cursor e ferramentas semelhantes, uma para o catálogo e uma para cada ferramenta. - Leia o índice do site. /llms.txt lista as ferramentas, a API e o endpoint MCP em texto simples, e
/site.jsonlddescreve o site como dados estruturados.
O artigo “Built for AI Agents, Not Just Browsers” no blog do PDF123 explica como a API REST e o MCP se encaixam.
Posso executar o PDF123 no meu próprio servidor?
Sim. O backend é o programa pdfx-server, que roda em Docker. Aponte o SDK, a linha de comando ou o servidor MCP para ele com PDFX_API_BASE, e seus arquivos ficam na sua rede. Veja Self-host para a configuração e Enterprise para as opções de suporte.
FAQ
A API do PDF123 é gratuita?
Sim, no uso anônimo. As chamadas à API pública não exigem conta nem chave. As respostas hospedadas incluem cabeçalhos de limite de taxa, para que um cliente possa desacelerar antes de receber uma resposta 429.
Preciso de uma chave de API?
Não, para a API REST, o SDK e a linha de comando quando você usa o site público. Sim, para o endpoint MCP hospedado em /mcp, que responde 401 sem o cabeçalho X-API-KEY. Você pode criar uma chave nesta página depois de entrar.
Qual é o limite de tamanho de arquivo?
O site aceita arquivos de até 500 MB cada. O corpo de uma requisição direta à API pode ter até 100 MiB, incluindo a estrutura multipart. O SDK envia entradas maiores em partes, automaticamente, quando o total passa de 95 MB.
Posso hospedar a API por conta própria?
Sim. Execute o servidor por conta própria e defina a base da API como o endereço dele. O SDK, a linha de comando e o servidor MCP local aceitam uma URL base personalizada.
Como informo um erro?
Copie os campos code, reason e detail da resposta de problema, mais o horário da requisição, e envie pela página de contato. Não envie o PDF em si, a menos que o suporte peça.
Devo usar o SDK, a linha de comando ou o MCP?
Use o SDK dentro de código TypeScript, a linha de comando para scripts e lotes de arquivos locais, e o MCP quando um agente de IA escolhe a ferramenta. Os três usam o mesmo catálogo e o mesmo servidor, então você pode combiná-los.