¿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.
| Interfaz | Ideal para | Instalación o dirección | Guía |
|---|---|---|---|
| API REST | Cualquier lenguaje, servidores, scripts de shell | https://pdf123.xyz/api/v1 | Referencia de la API |
| SDK de TypeScript | Código Node, Bun y de navegador que necesita tipos | npm install @pdf123/sdk | Guía del SDK |
| Línea de comandos | Terminales, tareas de CI, lotes de archivos locales | npm install -g @pdf123/cli | Guía de la CLI |
| MCP | Agentes de IA como Claude Code, Claude Desktop y Cursor | npx -y @pdf123/mcp o https://pdf123.xyz/mcp | Guí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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfLa misma unión con el SDK de 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" });La misma unión con la línea de comandos:
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…
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.pdfEl 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.
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ímite | Valor |
|---|---|
| Tamaño de archivo en el sitio web | 500 MB por archivo |
| Cuerpo de una solicitud directa a la API | 100 MiB, incluido el encuadre multipart |
| Subida por fragmentos | El 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 motivo | Estado HTTP | Significado |
|---|---|---|
bad_request | 400 | Parámetros o cuerpo multipart no válidos |
password_required | 400 | El PDF está cifrado y no se envió contraseña |
invalid_pdf | 400 | El archivo no es un PDF o está dañado; prueba Reparar PDF |
page_out_of_range | 400 | Una de las páginas solicitadas no existe |
not_found | 404 | Ruta de operación desconocida |
rate_limited | 429 | Cuota 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 herramienta | Endpoint de la API | Comando de la CLI | Qué hace |
|---|---|---|---|
| Unir | /general/merge-pdfs | pdfx merge | Une varios PDF en uno |
| Dividir | /general/split-pages | pdfx split | Separa un PDF en varios archivos |
| Comprimir | /misc/compress-pdf | pdfx compress | Recomprime los flujos del PDF para reducir su tamaño |
| Rotar | /general/rotate-pdf | pdfx rotate | Cambia la orientación de las páginas |
| Proteger | /security/add-password | pdfx protect | Cifra un PDF con una contraseña |
| Desbloquear | /security/remove-password | pdfx unlock | Quita la protección con contraseña |
| Marca de agua | /security/add-watermark | pdfx watermark | Añade una marca de agua de texto o de imagen |
| OCR | /misc/ocr-pdf | pdfx ocr | Lee un PDF escaneado y devuelve Markdown |
| PDF a Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Convierte un PDF en Markdown |
| PDF a Word | /convert/pdf/word | pdfx convert-to-word | Convierte un PDF en un archivo de Word editable |
| Información del documento | /security/get-info-on-pdf | pdfx get-info | Informa de metadatos, permisos, fuentes y estructura |
| Reparar | /misc/repair | pdfx repair | Reconstruye 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/mcppara los archivos de tu equipo y el endpoint alojado enhttps://pdf123.xyz/mcp. - Cargar una skill de agente. Las skills para agentes son archivos
SKILL.mdpara 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.jsonlddescribe 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.