Convertir PDF a Markdown en Node.js
Tres llamadas y listo: crea un trabajo, consulta hasta que esté listo y descarga Markdown limpio. El ejemplo de abajo es Node 18+ con el fetch global, sin dependencias, sin GPU, solo la API REST.
Revisar el resultado antes de usarlo
Usa la especificación OpenAPI actual. Comprueba errores HTTP, estados, plazo máximo de espera y truncated antes de descargar. Guarda las claves API en el servidor.
Procesamiento en servidor y almacenamiento temporal. Revisa cifras y errores OCR con el original.
Crear, consultar, descargar
La API de PDF a Markdown es una pequeña API de trabajos. Haces POST de un PDF (una URL o un archivo subido) a /api/v2/jobs con tu clave de API, recibes un job_id, consultas /api/v2/jobs/{job_id} hasta que el estado sea ready, y luego descargas el Markdown de /api/v2/jobs/{job_id}/download. El OCR, las tablas y las fórmulas se manejan en el servidor, así que no hay nada que instalar en tu app de Node.
El ejemplo completo
Guárdalo como convert.mjs y ejecuta node convert.mjs. Cambia la clave y la URL del PDF.
// Node 18+. Keep P2M_API_KEY in the server environment, never in a web page.
import { writeFile } from 'node:fs/promises';
const API = 'https://pdf2md.dev/api/v2';
const key = process.env.P2M_API_KEY;
if (!key) throw new Error('Set P2M_API_KEY');
const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
async function request(path, options = {}) {
for (let attempt = 0; attempt < 4; attempt++) {
const r = await fetch(API + path, {
...options,
headers: { Authorization: 'Bearer ' + key, ...options.headers },
signal: AbortSignal.timeout(30000),
});
if (r.status === 429 && attempt < 3) {
const delay = Number(r.headers.get('Retry-After') || 3);
if (!Number.isFinite(delay) || delay > 60) throw new Error('Rate limited; retry later');
await pause(Math.max(1, delay) * 1000);
continue;
}
if (!r.ok) throw new Error('HTTP ' + r.status + ': ' + (await r.text()).slice(0, 300));
return r;
}
}
const created = await (await request('/jobs', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ url: process.env.PDF_URL || 'https://example.com/document.pdf',
options: { image_mode: 'placeholder', ocr_lang: 'en' } }),
})).json();
if (!created.job_id) throw new Error('Missing job_id');
const deadline = Date.now() + 20 * 60 * 1000;
let job;
while (true) {
job = await (await request('/jobs/' + created.job_id)).json();
if (job.status === 'ready') break;
if (['error', 'canceled', 'deleted'].includes(job.status)) throw new Error('Job ended: ' + job.status);
if (Date.now() >= deadline) throw new Error('Polling deadline reached; the job may still be running');
await pause(3000);
}
const md = await (await request('/jobs/' + created.job_id + '/download')).text();
if (job.truncated) console.warn('Partial result; verify missing pages');
await writeFile('document.md', md, 'utf8');
El Idempotency-Key hace seguro un create reintentado: si se envía la misma clave dos veces, recibes el mismo trabajo en vez de una conversión duplicada.
Qué hace cada llamada
Crea un trabajo
POST /api/v2/jobs con la clave de API como token bearer y un cuerpo JSON de { "url": "..." }. Para convertir un archivo local, envía multipart/form-data con un campo file. La respuesta da un job_id.
Consulta hasta ready
GET /api/v2/jobs/{job_id} devuelve un status de queued, processing, ready o error. Consulta cada pocos segundos hasta que se asiente.
Descarga el Markdown
GET /api/v2/jobs/{job_id}/download devuelve el texto Markdown. Escríbelo en un archivo .md, pásalo a un LLM, o guárdalo para un pipeline RAG.
Errores, reintentos y archivos grandes
Maneja los fallos
processing_timeout, conversion_failed); error_message es seguro de registrar.ready significa un resultado parcial que alcanzó el límite de tiempo en un documento muy largo.Escálalo
Para convertir muchos PDF, ejecuta las mismas tres llamadas por archivo con un pequeño límite de concurrencia, o cambia de la consulta a webhooks para que te avisen cuando cada trabajo esté listo. El contrato es idéntico en TypeScript; tipa la respuesta job y listo.
¿Prefieres Python o la shell? Consulta el tutorial de Python y la receta de cURL.
¿Construyes un agente o pipeline?
La misma conversión está disponible como un endpoint MCP alojado, así que un agente de IA puede convertir PDF sin configuración. Consulta el hub para desarrolladores para la referencia completa de la API y la especificación OpenAPI.
Preguntas habituales
¿Necesito una clave de API para convertir PDF en Node.js?
Sí, para la API REST pasas una clave de API como token bearer. También puedes convertir de forma anónima en el navegador o la app web sin clave; la clave de API es para el uso programático y automatizado.
¿Qué versión de Node.js necesito?
Node 18 o superior, que incluye un fetch global, así el ejemplo no necesita dependencias extra. En versiones anteriores, instala un polyfill de fetch o usa una librería de peticiones.
¿Cómo convierto un archivo PDF local en vez de una URL?
Envía un POST multipart/form-data a /api/v2/jobs con el campo file apuntando al PDF, usando FormData y un Blob, en vez de un cuerpo JSON con url. El resto del flujo (consultar, descargar) es igual.
¿Cómo manejo los errores y tiempos de espera?
Cuando status es error, lee error_code (por ejemplo processing_timeout o conversion_failed) y error_message. Un documento largo puede terminar ready con truncated en true, lo que significa un resultado parcial que alcanzó el límite de tiempo.
¿Puedo usar webhooks en vez de consulta?
Sí. La consulta es lo más sencillo para empezar, pero la API también admite webhooks para que te avisen cuando un trabajo esté listo en vez de consultar. Consulta el hub para desarrolladores para la configuración del webhook.