Tutorial de Python

Convertir PDF a Markdown en Python

Un tutorial paso a paso usando la API REST: consigue una clave, crea un trabajo, consulta y descarga Markdown limpio, con un ejemplo completo y copiable y manejo de errores como es debido.

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.

Elegir los ajustes del PDF

Respuesta breve

Una clave, tres llamadas

Para convertir un PDF a Markdown en Python llamas a una pequeña API REST con una clave bearer: POST /api/v2/jobs para crear un trabajo, GET /api/v2/jobs/{id} para consultar hasta que esté listo, y luego GET /api/v2/jobs/{id}/download para el Markdown. No hay nada que alojar ni una librería pesada que instalar, solo requests. El mismo ciclo de vida se expone como un MCP alojado para agentes, y la salida es el mismo Markdown que producen la extensión y la app web, así puedes prototipar en el navegador y luego automatizar con confianza.

Cómo

Configúralo en cuatro pasos

1

Consigue una clave de API

Inicia sesión con una cuenta de Google gratuita y crea una clave de API en tu cuenta; se muestra una sola vez. Envíala como Authorization: Bearer p2m_your_key.

2

Crea un trabajo

Haz POST de la URL del PDF (o los bytes subidos) a /api/v2/jobs. Obtienes un id de trabajo y un estado.

3

Consulta hasta ready

Haz GET /api/v2/jobs/{id} hasta que status sea ready o error.

4

Descarga el Markdown

Haz GET /api/v2/jobs/{id}/download para el texto Markdown. Respeta truncated y pages.

Ejemplo completo

El script de Python completo

Librería estándar más requests. Crea desde una URL de PDF, consulta y luego guarda el Markdown.

import os, time
from pathlib import Path
import requests

API = "https://pdf2md.dev/api/v2"
H = {"Authorization": "Bearer " + os.environ["P2M_API_KEY"]}

def call(method, path, **kwargs):
    for attempt in range(4):
        r = requests.request(method, API + path, headers=H, timeout=30, **kwargs)
        if r.status_code != 429:
            r.raise_for_status()
            return r
        if attempt == 3:
            r.raise_for_status()
        try:
            delay = float(r.headers.get("Retry-After", "3"))
        except ValueError:
            delay = 3
        if delay > 60:
            raise RuntimeError("Retry later: rate limit")
        time.sleep(max(1, delay))

# URL must point to a publicly accessible PDF, not an HTML document viewer.
created = call("POST", "/jobs", json={
    "url": os.environ.get("PDF_URL", "https://example.com/document.pdf"),
    "options": {"image_mode": "placeholder", "ocr_lang": "en"}
}).json()
jid = created["job_id"]
deadline = time.monotonic() + 20 * 60
while True:
    job = call("GET", f"/jobs/{jid}").json()
    if job["status"] == "ready":
        break
    if job["status"] in ("error", "canceled", "deleted"):
        raise RuntimeError(f"Job ended: {job['status']} {job.get('error_code', '')}")
    if time.monotonic() >= deadline:
        raise TimeoutError("Polling deadline reached; the job may still be running")
    time.sleep(3)
md = call("GET", f"/jobs/{jid}/download").text
if job.get("truncated"):
    print("WARNING: partial result; verify missing pages")
Path("document.md").write_text(md, encoding="utf-8")

¿Subir un archivo local en vez de una URL? Haz POST de los bytes como multipart/form-data con un campo file al mismo endpoint. Las formas completas de la petición y la respuesta están en la especificación OpenAPI.

Para convertir muchos PDF, crea un trabajo por archivo y consúltalos en paralelo hasta tu límite de espacios (3 en el plan gratuito, más en los de pago). Mantén un Idempotency-Key distinto por archivo para que los reintentos nunca dupliquen trabajo, y espera ante un 429 usando la cabecera Retry-After.

Hazlo robusto

Errores, reintentos y webhooks

Lee el código de error

Un trabajo fallido devuelve status: error con un error_code legible por máquina (processing_timeout o conversion_failed) y un error_message seguro: ramifica según el código, no el texto.

Maneja truncated

Un documento largo puede volver ready con truncated=true. Comprueba la marca y divide el archivo o usa un presupuesto de pago mayor.

Idempotency-Key

Envía una cabecera Idempotency-Key para que un create reintentado devuelva el mismo trabajo en vez de duplicar trabajo.

Webhooks en vez de consulta

En planes de pago, registra un webhook o pasa callback_url y recibe un POST en ready/error en vez de consultar.

Respeta el 429

Ante un 429, espera los segundos de Retry-After antes de reintentar; no satures la cola.

Guarda las claves en el servidor

La clave es un secreto: guárdala en el servidor, envíala por TLS, y rótala o revócala cuando quieras.

Otros lenguajes

¿No usas Python? Las mismas tres llamadas

Es una API HTTPS simple, así que cualquier lenguaje funciona. El mismo crear / consultar / descargar en Node:

// 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');

¿Prefieres herramientas de agente o RAG?

El mismo ciclo de vida es un MCP alojado para ChatGPT, Claude y frameworks de agentes. Para ingesta y chunking, consulta la guía de RAG.

Preguntas frecuentes

Preguntas habituales

¿Cómo convierto un PDF a Markdown en Python?

Llama a la API REST con una clave bearer: haz POST del PDF a /api/v2/jobs, consulta GET /api/v2/jobs/{id} hasta ready, y luego haz GET de /download para el Markdown. El ejemplo completo con requests está arriba.

¿Necesito una clave de API?

Sí para la API. Una cuenta de Google gratuita te permite crear una clave y usar el MCP alojado. La extensión del navegador y la app web siguen siendo anónimas y no necesitan clave.

¿Cómo manejo los errores y tiempos de espera?

Un trabajo fallido devuelve status: error con un error_code legible por máquina (processing_timeout o conversion_failed) y un error_message seguro. Un documento largo puede volver ready con truncated=true; comprueba esa marca.

¿Puedo evitar la consulta?

En planes de pago, registra un webhook o pasa callback_url al crear el trabajo, y el servicio te hace POST en ready o error para que no consultes.

¿Funciona desde Node u otros lenguajes?

Sí. Es una API HTTPS simple, así que cualquier lenguaje funciona. Arriba hay un ejemplo corto en Node, y el contrato completo está en la especificación OpenAPI.

¿Cómo convierto un archivo local en vez de una URL?

Haz POST de los bytes del archivo como multipart/form-data con un campo file a /api/v2/jobs, en vez de un cuerpo JSON con url. Los pasos de consultar y descargar son idénticos.

¿Puedo convertir muchos PDF a la vez?

Crea un trabajo por archivo y consúltalos en paralelo hasta tu límite de espacios (3 en el plan gratuito, más en los de pago). Los planes de pago añaden un endpoint de creación por lotes y webhooks para que no consultes nada.

¿La salida es la misma que la de la extensión y la app web?

Sí. Cada superficie usa el mismo motor de conversión, así que la API devuelve el mismo Markdown que obtendrías en el navegador.

¿Es gratis?

El plan gratuito ofrece 3 espacios, archivos de 10 MB, un presupuesto de tiempo de 15 minutos y retención de 1 hora. Los planes de pago amplían cada límite y añaden webhooks y creación por lotes.