Convertir PDF a Markdown con cURL
Sin lenguaje de programación. Con curl y jq puedes convertir un PDF a Markdown directamente desde la terminal, un Makefile, un paso de CI o un cron. Copia la receta de abajo, pon tu clave y ejecútala.
Tres curls y un bucle de consulta
curl -X POST del PDF a /api/v2/jobs con tu clave, saca el job_id con jq, haz un bucle sobre /api/v2/jobs/{job_id} hasta que el estado sea ready, y luego haz curl a /api/v2/jobs/{job_id}/download con -o para guardar el Markdown. Es HTTP puro, así que corre donde corra una shell, sin SDK y sin nada que compilar.
La receta de shell completa
Guárdala como convert.sh, chmod +x, y ejecútala. Cambia tu clave y el PDF.
#!/usr/bin/env bash set -euo pipefail API="https://pdf2md.dev/api/v2" AUTH="Authorization: Bearer p2m_your_key" # 1) crear un trabajo desde una URL de PDF # (para subir un archivo local, usa: -F [email protected] ) JID=$(curl -fsS -X POST "$API/jobs" -H "$AUTH" \ -H "Content-Type: application/json" -H "Idempotency-Key: report-2026-01" \ -d '{"url":"https://example.com/report.pdf"}' | jq -r .job_id) # 2) consultar hasta ready o error while :; do JOB=$(curl -fsS "$API/jobs/$JID" -H "$AUTH") STATUS=$(echo "$JOB" | jq -r .status) [ "$STATUS" = "ready" ] && break if [ "$STATUS" = "error" ]; then echo "failed: $(echo "$JOB" | jq -r .error_code)" >&2 exit 1 fi sleep 3 done # 3) descargar el Markdown curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o report.md echo "guardado report.md"
La opción -f hace que curl falle ante errores HTTP, y set -euo pipefail detiene el script al primer problema, así una ejecución rota nunca escribe un archivo vacío en silencio.
Hecho para la automatización
Como es un único script autónomo con un código de salida real, la receta encaja donde un programa completo sería excesivo.
Pipelines de CI
Añádela como paso de build para convertir PDF de documentación a Markdown en cada commit. Una conversión fallida hace fallar el paso.
Trabajos cron
Prográmala para descargar y convertir un informe nocturno, escribiendo el Markdown donde tu sitio de documentación o tu pipeline lo esperan.
Secretos, no literales
Guarda la clave de API en un secreto de CI o una variable de entorno y referénciala en la cabecera Authorization, nunca incrustada en el código.
¿La quieres dentro de una app? Consulta los tutoriales de Python, Node.js y Go.
Otras shells y webhooks
La receta es bash, pero las tres llamadas son solo HTTP, así que se portan a cualquier sitio donde corra curl.
Windows y PowerShell
curl viene con el Windows moderno, así que las mismas llamadas funcionan en PowerShell o un archivo .cmd; solo ajustas el entrecomillado (PowerShell prefiere comillas simples alrededor del JSON, o usa Invoke-RestMethod con un cuerpo de hashtable). En un Makefile, un paso de build de Dockerfile o un bloque run: de GitHub Actions, el script no cambia.
Sáltate el bucle de consulta
La consulta es lo más sencillo y vale para un archivo o unos pocos. Para muchos archivos, o para evitar la espera por completo, registra un webhook y la API te llama de vuelta cuando un trabajo está listo, así un script puede lanzar conversiones y procesar resultados a medida que llegan en vez de hacer un bucle.
Sea cual sea la shell, mantén la clave fuera del cuerpo del script: léela de una variable de entorno o un secreto de CI. Y si necesitas inspeccionar un resultado antes de guardarlo, canaliza la descarga a un visor (curl ... | less) en vez de -o, ya que el endpoint devuelve texto Markdown plano.
Preguntas habituales
¿Qué necesito para ejecutar la receta de cURL?
Solo curl y jq. curl hace las llamadas HTTP y jq lee job_id y status de las respuestas JSON. Ambos están disponibles en la mayoría de sistemas o a una instalación de paquete de distancia.
¿Cómo convierto un archivo local con curl?
Usa una subida multipart: curl -X POST /api/v2/jobs -F [email protected] con la cabecera Authorization, en vez del cuerpo JSON -d que lleva una url.
¿Cómo uso esto en CI o un cron?
El script sale con un código distinto de cero cuando un trabajo falla, así encaja en un paso de CI o un cron programado. Guarda la clave de API como un secreto de CI o una variable de entorno y pásala en la cabecera Authorization.
¿Puedo hacerlo sin jq?
jq es la forma más limpia de leer job_id y status, pero también puedes parsear el JSON con grep y sed si jq no está disponible. Se recomienda jq por fiabilidad.
¿Qué hace la cabecera Idempotency-Key?
Enviar la misma Idempotency-Key en un create reintentado devuelve el mismo trabajo en vez de iniciar una conversión duplicada, lo cual es útil cuando un paso de CI inestable se reejecuta.