Ligne de commande

Convertir un PDF en Markdown avec cURL

Q: De quoi ai-je besoin pour exécuter la recette cURL ?

Seulement curl et jq. curl effectue les appels HTTP et jq lit job_id et status dans les réponses JSON. Les deux sont disponibles sur la plupart des systèmes ou à une installation de paquet près.

Q: Comment convertir un fichier local avec curl ?

Utilisez un envoi multipart : curl -X POST /api/v2/jobs -F file=@report.pdf avec l'en-tête Authorization, au lieu du corps JSON -d qui porte une url.

Q: Puis-je le faire sans jq ?

jq est la façon la plus propre de lire job_id et status, mais vous pouvez aussi analyser le JSON avec grep et sed si jq n'est pas disponible. jq est recommandé pour la fiabilité.

Q: À quoi sert l'en-tête Idempotency-Key ?

Envoyer la même Idempotency-Key sur une création réessayée renvoie le même travail au lieu de lancer une conversion en double, ce qui est utile lorsqu'une étape de CI instable se relance.

Aucun langage de programmation requis. Avec curl et jq, vous pouvez convertir un PDF en Markdown directement depuis le terminal, un Makefile, une étape de CI ou un cron. Copiez la recette ci-dessous, définissez votre clé et exécutez-la.

Hub développeurs Essayer sur le web

Réponse brève

Trois curls et une boucle de consultation

curl -X POST du PDF vers /api/v2/jobs avec votre clé, extrayez le job_id avec jq, bouclez sur /api/v2/jobs/{job_id} jusqu'à ce que le statut soit ready, puis faites curl vers /api/v2/jobs/{job_id}/download avec -o pour enregistrer le Markdown. C'est du HTTP pur, donc cela s'exécute partout où s'exécute un shell, sans SDK et sans rien à compiler.

Comment faire

La recette shell complète

Enregistrez-la sous convert.sh, chmod +x, et exécutez-la. Remplacez votre clé et le PDF.

#!/usr/bin/env bash
set -euo pipefail
API="https://pdf2md.dev/api/v2"
AUTH="Authorization: Bearer p2m_your_key"

# 1) create a job from a PDF URL
#    (to upload a local file instead, use: -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) poll until ready or 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) download the Markdown
curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o report.md
echo "saved report.md"

L'option -f fait échouer curl en cas d'erreurs HTTP, et set -euo pipefail arrête le script au premier problème, ainsi une exécution cassée n'écrit jamais silencieusement un fichier vide.

Où cela s'intègre

Conçu pour l'automatisation

Comme c'est un unique script autonome avec un vrai code de sortie, la recette s'intègre là où un programme complet serait excessif.

Pipelines de CI

Ajoutez-la comme étape de build pour convertir des PDF de documentation en Markdown à chaque commit. Une conversion échouée fait échouer l'étape.

Travaux cron

Planifiez-la pour télécharger et convertir un rapport nocturne, en écrivant le Markdown là où votre site de documentation ou votre pipeline l'attend.

Des secrets, pas des littéraux

Conservez la clé API dans un secret de CI ou une variable d'environnement et référencez-la dans l'en-tête Authorization, jamais codée en dur.

Vous la voulez plutôt dans une app ? Consultez les tutoriels Python, Node.js et Go.

Au-delà de bash

Autres shells et webhooks

La recette est en bash, mais les trois appels ne sont que du HTTP, ils se portent donc partout où s'exécute curl.

Windows et PowerShell

curl est livré avec le Windows moderne, donc les mêmes appels fonctionnent dans PowerShell ou un fichier .cmd ; vous ajustez seulement la mise entre guillemets (PowerShell préfère les guillemets simples autour du JSON, ou utilisez Invoke-RestMethod avec un corps de hashtable). Dans un Makefile, une étape de build de Dockerfile ou un bloc run: de GitHub Actions, le script reste inchangé.

Sautez la boucle de consultation

La consultation est l'approche la plus simple et convient pour un fichier ou une poignée. Pour de nombreux fichiers, ou pour éviter l'attente entièrement, enregistrez un webhook et l'API vous rappelle lorsqu'un travail est prêt, ainsi un script peut lancer des conversions et traiter les résultats à mesure qu'ils arrivent au lieu de boucler.

Quel que soit le shell, gardez la clé hors du corps du script : lisez-la depuis une variable d'environnement ou un secret de CI. Et si vous devez inspecter un résultat avant de l'enregistrer, canalisez le téléchargement vers une visionneuse (curl ... | less) au lieu de -o, puisque l'endpoint renvoie du texte Markdown brut.

FAQ

Questions fréquentes

De quoi ai-je besoin pour exécuter la recette cURL ?

Seulement curl et jq. curl effectue les appels HTTP et jq lit job_id et status dans les réponses JSON. Les deux sont disponibles sur la plupart des systèmes ou à une installation de paquet près.

Comment convertir un fichier local avec curl ?

Utilisez un envoi multipart : curl -X POST /api/v2/jobs -F [email protected] avec l'en-tête Authorization, au lieu du corps JSON -d qui porte une url.

Comment utiliser ceci en CI ou dans un cron ?

Le script sort avec un code différent de zéro lorsqu'un travail échoue, il s'intègre donc dans une étape de CI ou un cron planifié. Stockez la clé API comme un secret de CI ou une variable d'environnement et passez-la dans l'en-tête Authorization.

Puis-je le faire sans jq ?

jq est la façon la plus propre de lire job_id et status, mais vous pouvez aussi analyser le JSON avec grep et sed si jq n'est pas disponible. jq est recommandé pour la fiabilité.

À quoi sert l'en-tête Idempotency-Key ?

Envoyer la même Idempotency-Key sur une création réessayée renvoie le même travail au lieu de lancer une conversion en double, ce qui est utile lorsqu'une étape de CI instable se relance.