Ir al contenido principal
PPDF123

PDF123 para desarrolladores: API REST, SDK, línea de comandos y MCP

La plataforma para desarrolladores de PDF123 ofrece las mismas 97 herramientas PDF mediante cuatro interfaces: una API REST descrita con OpenAPI, un SDK de TypeScript, la línea de comandos pdfx y servidores MCP para agentes de IA. Las llamadas anónimas no requieren cuenta ni clave de API.

En esta página

¿Cómo puedo usar PDF123 desde código?

Las cuatro interfaces llaman a las mismas operaciones, así que una unión de archivos da el mismo resultado en todas. Elige según dónde se ejecute tu código.

InterfazIdeal paraInstalación o direcciónGuía
API RESTCualquier lenguaje, servidores, scripts de shellhttps://pdf123.xyz/api/v1Referencia de la API
SDK de TypeScriptCódigo Node, Bun y de navegador que necesita tiposnpm install @pdf123/sdkGuía del SDK
Línea de comandosTerminales, tareas de CI, lotes de archivos localesnpm install -g @pdf123/cliGuía de la CLI
MCPAgentes de IA como Claude Code, Claude Desktop y Cursornpx -y @pdf123/mcp o https://pdf123.xyz/mcpGuía de MCP

Usa la API REST si tu código no está en TypeScript. Usa el SDK si lo está, porque las opciones de cada herramienta están tipadas y se comprueban antes de subir nada. Usa la línea de comandos para tareas puntuales y scripts de shell. Usa MCP cuando un agente de IA deba decidir qué herramienta ejecutar.

El catálogo tiene 97 herramientas. 58 de ellas tienen página en este sitio, como Unir PDF, Dividir PDF y Comprimir PDF. Las demás son operaciones del backend sin página web, y todas están disponibles en el SDK, en la línea de comandos y en MCP.

¿Cómo ejecuto mi primera solicitud?

Une dos archivos con curl. La solicitud es un formulario multipart con una parte fileInput por archivo.

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

La misma unión con el SDK de TypeScript:

SDK: merge two 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" });

La misma unión con la línea de comandos:

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

¿Cómo funciona la autenticación?

Las llamadas anónimas a la API pública no necesitan cuenta ni clave. Envía una clave de API en la cabecera X-API-KEY cuando quieras identificar tu tráfico o llamar al endpoint MCP alojado, que siempre exige una clave.

Inicia sesión para crear una clave en el panel de abajo y guárdala en un lugar seguro.

Comprobando tu sesión…

Call the API with a keybash
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

El SDK recibe la clave como apiKey. La línea de comandos y el servidor MCP local la leen de la variable de entorno PDFX_API_KEY.

Nota

En un servidor autohospedado, define la variable de entorno SECURITY_CUSTOMGLOBALAPIKEY para fijar una clave que el servidor acepte. Consulta Autohospedaje.

¿Dónde está la referencia de la API?

La API REST se documenta de dos formas. Swagger UI permite probar cada endpoint en el navegador. El documento OpenAPI es la fuente legible por máquinas para los generadores de clientes.

Cada operación es un POST bajo la URL base https://pdf123.xyz/api/v1, agrupada por categoría. Por ejemplo, unir es /general/merge-pdfs y comprimir es /misc/compress-pdf.

¿Cómo encadeno varias herramientas en una sola solicitud?

POST /api/v1/pipeline recibe las partes fileInput y un campo steps. El campo steps es un array JSON de objetos con un op y, opcionalmente, params. Cada paso recibe la salida del paso anterior.

Merge, then compress, in one requestbash
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

¿Cómo reintento una solicitud con seguridad?

Envía una cabecera Idempotency-Key en cualquier operación. Si la misma solicitud se repite en un plazo de 24 horas, se devuelve el primer resultado con la cabecera Idempotency-Replayed: true en lugar de ejecutarla de nuevo. Si usas la misma clave para otra solicitud distinta, se rechaza. Los resultados de más de 32 MiB no se almacenan, así que repetir una solicitud de ese tipo devuelve 409 y exige una clave nueva.

¿Cuáles son los límites de tamaño y de frecuencia?

LímiteValor
Tamaño de archivo en el sitio web500 MB por archivo
Cuerpo de una solicitud directa a la API100 MiB, incluido el encuadre multipart
Subida por fragmentosEl SDK pasa automáticamente a la API de subida cuando el total supera 95 MB

Las respuestas incluyen las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta con estado 429 añade Retry-After. Lee las cabeceras en lugar de suponer una cuota fija, porque un servidor autohospedado define sus propios límites. La entrada del blog sobre el límite de tamaño de solicitud explica el error que recibes con un cuerpo demasiado grande.

¿Qué aspecto tiene un error?

Los fallos devuelven application/problem+json con los campos type, title, status, detail, code, reason y hint. Ramifica según reason y recurre a code si falta. El texto de detail está escrito para personas y nunca contiene salida sin procesar de la herramienta. Todos los códigos figuran en Códigos de error.

Código o motivoEstado HTTPSignificado
bad_request400Parámetros o cuerpo multipart no válidos
password_required400El PDF está cifrado y no se envió contraseña
invalid_pdf400El archivo no es un PDF o está dañado; prueba Reparar PDF
page_out_of_range400Una de las páginas solicitadas no existe
not_found404Ruta de operación desconocida
rate_limited429Cuota agotada; espera el valor de Retry-After

¿Qué herramientas puedo llamar primero?

Estas doce herramientas cubren la mayoría de las solicitudes. Usa la página de la herramienta para probarla en el navegador.

Página de la herramientaEndpoint de la APIComando de la CLIQué hace
Unir/general/merge-pdfspdfx mergeUne varios PDF en uno
Dividir/general/split-pagespdfx splitSepara un PDF en varios archivos
Comprimir/misc/compress-pdfpdfx compressRecomprime los flujos del PDF para reducir su tamaño
Rotar/general/rotate-pdfpdfx rotateCambia la orientación de las páginas
Proteger/security/add-passwordpdfx protectCifra un PDF con una contraseña
Desbloquear/security/remove-passwordpdfx unlockQuita la protección con contraseña
Marca de agua/security/add-watermarkpdfx watermarkAñade una marca de agua de texto o de imagen
OCR/misc/ocr-pdfpdfx ocrLee un PDF escaneado y devuelve Markdown
PDF a Markdown/convert/pdf/markdownpdfx pdf-to-markdownConvierte un PDF en Markdown
PDF a Word/convert/pdf/wordpdfx convert-to-wordConvierte un PDF en un archivo de Word editable
Información del documento/security/get-info-on-pdfpdfx get-infoInforma de metadatos, permisos, fuentes y estructura
Reparar/misc/repairpdfx repairReconstruye la estructura de un PDF dañado

Los endpoints son relativos a https://pdf123.xyz/api/v1. Ejecuta pdfx list o abre el documento OpenAPI para ver las 97 herramientas.

¿Cómo uso PDF123 desde un agente de IA?

Un agente puede usar las herramientas de tres maneras:

  • Conectar un servidor MCP. La guía de MCP describe el servidor local @pdf123/mcp para los archivos de tu equipo y el endpoint alojado en https://pdf123.xyz/mcp.
  • Cargar una skill de agente. Las skills para agentes son archivos SKILL.md para Claude Code, Codex, Cursor y herramientas similares: una para el catálogo y otra para cada herramienta.
  • Leer el índice del sitio. /llms.txt enumera en texto plano las herramientas, la API y el endpoint MCP, y /site.jsonld describe el sitio como datos estructurados.

La entrada «Built for AI Agents, Not Just Browsers» del blog de PDF123 explica cómo encajan la API REST y MCP.

¿Puedo ejecutar PDF123 en mi propio servidor?

Sí. El backend es el programa pdfx-server, que se ejecuta en Docker. Apunta el SDK, la línea de comandos o el servidor MCP hacia él con PDFX_API_BASE y tus archivos no saldrán de tu red. Consulta Autohospedaje para la instalación y Empresas para las opciones de soporte.

Preguntas frecuentes

¿Es gratuita la API de PDF123?

Sí, en el uso anónimo. Las llamadas a la API pública no necesitan cuenta ni clave. Las respuestas del servicio alojado incluyen cabeceras de límite de frecuencia, de modo que un cliente puede reducir el ritmo antes de recibir una respuesta 429.

¿Necesito una clave de API?

No para la API REST, el SDK ni la línea de comandos cuando usas el sitio público. Sí para el endpoint MCP alojado en /mcp, que responde 401 si falta la cabecera X-API-KEY. Puedes crear una clave en esta página después de iniciar sesión.

¿Cuál es el límite de tamaño de archivo?

El sitio web admite archivos de hasta 500 MB cada uno. El cuerpo de una solicitud directa a la API puede llegar a 100 MiB, incluido el encuadre multipart. El SDK sube las entradas más grandes por fragmentos de forma automática cuando el total supera 95 MB.

¿Puedo autohospedar la API?

Sí. Ejecuta el servidor por tu cuenta y define la base de la API con su dirección. El SDK, la línea de comandos y el servidor MCP local aceptan una URL base personalizada.

¿Cómo notifico un error?

Copia los campos code, reason y detail de la respuesta de problema, junto con la hora de la solicitud, y envíalos a través de la página de contacto. No envíes el PDF en sí salvo que el soporte te lo pida.

¿Debo usar el SDK, la línea de comandos o MCP?

Usa el SDK dentro de código TypeScript, la línea de comandos para scripts y lotes de archivos locales, y MCP cuando sea un agente de IA quien elija la herramienta. Los tres usan el mismo catálogo y el mismo servidor, así que puedes combinarlos.