Convertir PDF a Markdown por lotes
¿Tienes una carpeta de informes, artículos o facturas? Conviértelos todos con la API REST: un pequeño trabajo por archivo, iterado sobre tu conjunto, con reintentos seguros por idempotencia para que una reejecución nunca duplique trabajo.
Un lote son muchos trabajos pequeños
La API convierte un PDF por trabajo: crear, consultar, descargar. Para convertir muchos, ejecutas ese flujo una vez por archivo en un bucle, con dos añadidos que hacen fiable un lote. Una Idempotency-Key por archivo significa que una reejecución tras una caída retoma donde lo dejó en vez de rehacer el trabajo terminado. Un pequeño límite de concurrencia mantiene varias conversiones en vuelo sin saturar la API. Esa misma forma escala de diez archivos a miles.
Convierte una carpeta entera
Un bucle de shell mínimo sobre cada PDF de un directorio. Cambia tu clave.
API="https://pdf2md.dev/api/v2"
AUTH="Authorization: Bearer p2m_your_key"
for pdf in *.pdf; do
# el nombre del archivo como Idempotency-Key: una reejecución reutiliza el mismo trabajo
JID=$(curl -fsS -X POST "$API/jobs" -H "$AUTH" \
-H "Idempotency-Key: $pdf" -F file=@"$pdf" | jq -r .job_id)
until [ "$(curl -fsS "$API/jobs/$JID" -H "$AUTH" | jq -r .status)" = "ready" ]; do
sleep 3
done
curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o "${pdf%.pdf}.md"
echo "convertido $pdf"
done
Esta versión es secuencial por claridad. Para volumen real, convierte varios archivos a la vez con un pool de workers y cambia de la consulta a webhooks, así te avisan a medida que cada trabajo termina.
De una carpeta a un pipeline
Concurrencia
Convierte varios archivos a la vez con un pool de workers acotado. Empieza con unos cinco en vuelo y ajusta a tu plan.
Reintentos idempotentes
Una clave estable por archivo (nombre o hash de contenido) hace segura una reejecución, así un lote a medias se reanuda limpiamente.
Webhooks
Para miles de archivos, deja que los webhooks te digan cuándo está listo cada trabajo en vez de consultarlos todos.
Manejar los fallos en un lote
En una ejecución real, algunos archivos estarán protegidos con contraseña, corruptos o serán demasiado grandes. El objetivo es dejar que el lote termine y te diga qué se saltó, no detenerse al primer archivo malo.
Salta y registra, no te detengas
Cuando un trabajo vuelva con status: error, registra el nombre del archivo y su error_code en un log y sigue. Al final tienes un conjunto limpio de archivos Markdown más una lista corta de los que necesitan atención, en vez de un lote que murió a mitad.
Reanuda con seguridad
Como cada create usa el nombre del archivo (o un hash de contenido) como su Idempotency-Key, reejecutar todo el lote es seguro: los archivos terminados devuelven su trabajo existente, y solo los que fallaron o no se procesaron hacen trabajo real. Un cron nocturno puede reejecutar la misma carpeta sin rehacerlo todo.
Dos detalles más mantienen ordenadas las ejecuciones grandes. Escribe cada resultado junto a su origen (report.pdf pasa a report.md) para que el mapeo sea obvio, y comprueba la marca truncated en cada trabajo, ya que un documento muy largo puede volver como resultado parcial que alcanzó el límite de tiempo. En el plan gratuito los límites de espacios y tamaño son más bajos, así que un lote grande es buena razón para pasar a un plan de pago, que amplía la concurrencia, el tamaño de archivo y el cupo mensual de páginas.
¿Alimentas una base de conocimiento?
Un lote de PDF se convierte en una carpeta de Markdown limpio, lista para trocear e incrustar. Consulta la guía de RAG para convertir esa salida en contexto recuperable.
Preguntas habituales
¿Cómo convierto muchos PDF a la vez?
Ejecuta el flujo de crear, consultar y descargar por archivo en un bucle. Usa una Idempotency-Key por archivo para que una reejecución no duplique trabajo, y un pequeño límite de concurrencia para ser amable con la API.
¿Hay un único endpoint masivo?
La conversión es por trabajo, así que un lote son muchos trabajos. El mismo bucle escala de unos pocos archivos a miles; añade concurrencia y webhooks para ejecuciones grandes.
¿Cómo evito reconvertir archivos en un reintento?
Pasa una Idempotency-Key estable al crear, por ejemplo el nombre del archivo o un hash del contenido. La misma clave devuelve el mismo trabajo en vez de iniciar una conversión duplicada.
¿Cuántos puedo ejecutar en paralelo?
Empieza con un pool pequeño, por ejemplo cinco, y ajústalo. El plan gratuito tiene límites de espacios más bajos; los planes de pago amplían los espacios y el rendimiento.
¿Puedo usar webhooks en vez de consultar cada trabajo?
Sí. Para lotes grandes, los webhooks te avisan a medida que cada trabajo termina, lo que escala mejor que consultar miles de trabajos. Consulta el hub para desarrolladores.