Ir para o conteúdo principal
PPDF123

PDF123 para desenvolvedores: API REST, SDK, linha de comando e MCP

A plataforma para desenvolvedores do PDF123 oferece as mesmas 97 ferramentas de PDF por quatro interfaces: uma API REST descrita em OpenAPI, um SDK TypeScript, a linha de comando pdfx e servidores MCP para agentes de IA. Chamadas anônimas não exigem conta nem chave de API.

Nesta página

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.

InterfaceIdeal paraInstalação ou endereçoGuia
API RESTQualquer linguagem, servidores, scripts de shellhttps://pdf123.xyz/api/v1Referência da API
SDK TypeScriptCódigo Node, Bun e de navegador que precisa de tiposnpm install @pdf123/sdkGuia do SDK
Linha de comandoTerminais, tarefas de CI, lotes de arquivos locaisnpm install -g @pdf123/cliGuia da CLI
MCPAgentes de IA como Claude Code, Claude Desktop e Cursornpx -y @pdf123/mcp ou https://pdf123.xyz/mcpGuia 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.

REST: juntar dois PDFsbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

A mesma junção com o SDK TypeScript:

SDK: juntar dois PDFsts
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:

CLI: juntar dois PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Como 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…

Chamar a API com uma chavebash
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.pdf

O 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.

Juntar e depois comprimir, em uma requisiçãobash
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.pdf

Como 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?

LimiteValor
Tamanho de arquivo no site500 MB por arquivo
Corpo de uma requisição direta à API100 MiB, incluindo a estrutura multipart
Envio em partesO 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 motivoStatus HTTPSignificado
bad_request400Parâmetros ou corpo multipart inválidos
password_required400O PDF está criptografado e nenhuma senha foi enviada
invalid_pdf400O arquivo não é um PDF ou está danificado; tente Reparar PDF
page_out_of_range400Uma página solicitada não existe
not_found404Caminho de operação desconhecido
rate_limited429Cota 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 ferramentaEndpoint da APIComando da CLIO que faz
Juntar/general/merge-pdfspdfx mergeCombina vários PDFs em um só
Dividir/general/split-pagespdfx splitDivide um PDF em arquivos separados
Comprimir/misc/compress-pdfpdfx compressRecomprime os fluxos do PDF para reduzir o tamanho
Girar/general/rotate-pdfpdfx rotateMuda a orientação das páginas
Proteger/security/add-passwordpdfx protectCriptografa um PDF com senha
Desbloquear/security/remove-passwordpdfx unlockRemove a proteção por senha
Marca d'água/security/add-watermarkpdfx watermarkAdiciona uma marca d'água de texto ou imagem
OCR/misc/ocr-pdfpdfx ocrLê um PDF digitalizado e devolve Markdown
PDF para Markdown/convert/pdf/markdownpdfx pdf-to-markdownConverte um PDF em Markdown
PDF para Word/convert/pdf/wordpdfx convert-to-wordConverte um PDF em um arquivo Word editável
Informações do documento/security/get-info-on-pdfpdfx get-infoInforma metadados, permissões, fontes e estrutura
Reparar/misc/repairpdfx repairReconstró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 em https://pdf123.xyz/mcp.
  • Carregue uma skill de agente. Skills para agentes são arquivos SKILL.md para 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.jsonld descreve 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.