Hub développeurs

Développez avec l'API PDF vers Markdown

Un cycle de vie des tâches prévisible sur une API REST et un MCP hébergé équivalent : créez une tâche, attendez ready, récupérez le Markdown, libérez l'emplacement. L'API et le MCP ne contournent jamais les limites du produit.

Vérifier le résultat avant utilisation

Consultez l’OpenAPI actuelle. Vérifiez les erreurs HTTP, les états du travail, un délai maximal et truncated avant le téléchargement. Gardez les clés API côté serveur.

Traitement sur serveur et conservation temporaire. Vérifiez chiffres et erreurs OCR dans l’original.

Choisir les réglages du PDF

En un coup d'œil

Deux surfaces, un seul moteur

Choisissez l'intégration qui vous convient. Les deux appellent le même moteur de conversion et obéissent aux mêmes emplacements, limites et conservation.

API REST

Des endpoints HTTPS avec une clé d'API bearer. DTO stables, erreurs prévisibles, création idempotente.

Voir le cycle de vie

MCP hébergé

Un endpoint Model Context Protocol géré qui expose la conversion sous forme d'outils d'agent : une fine couche au-dessus de la même API.

Connecter le MCP

Custom GPT Actions

Importez un spec OpenAPI réduit dans un Custom GPT de ChatGPT pour qu'il convertisse les PDF comme outil intégré.

Configurer l'action
Authentification

Clés d'API bearer sur HTTPS

L'API et le MCP utilisent des clés d'API bearer, distinctes de la voie signée par appareil qu'utilise l'extension Chrome. Un compte Google gratuit est requis pour générer des clés.

Obtenir une clé

  • Connectez-vous avec Google (compte gratuit).
  • Générez une clé d'API dans votre compte ; elle est affichée une seule fois.
  • Envoyez-la comme Authorization: Bearer p2m_… à chaque requête.
  • Les clés sont des secrets : conservez-les côté serveur, faites-les tourner et révoquez-les à tout moment.

Des valeurs par défaut honnêtes

Des clés, pas des mots de passe. L'extension reste anonyme et signée par appareil ; les clés d'API/MCP sont une identification distincte, liée au compte.
HTTPS uniquement. Envoyez toujours les clés via TLS ; n'intégrez jamais une clé dans du code côté client livré aux utilisateurs.
Création idempotente. Une Idempotency-Key facultative à la création vous permet de réessayer sans risque, sans tâches en double.

Scopes. Chaque clé d'API porte des scopes : jobs:create, jobs:read, jobs:download, jobs:delete (ceux par défaut), plus settings:read / settings:write. Émettez des clés au moindre privilège ; l'API REST comme les outils MCP appliquent les scopes de la clé.

API REST

Créez une tâche, attendez, récupérez le Markdown, libérez l'emplacement

Un cycle de vie prévisible, deux façons de le piloter : appelez l'API REST depuis votre propre code, ou utilisez les outils équivalents du MCP hébergé. Ne revendiquez jamais un résultat avant status=ready.

API REST MCP hébergé
1

Créez la tâche

Faites un POST d'une URL de PDF ou téléversez des octets. Vous recevez un id de tâche et un emplacement. Idempotency-Key est respecté mais facultatif.

POST /api/v2/jobsmcp · pdf_to_markdown_create_job_from_url
2

Consultez le statut

Interrogez la tâche jusqu'à ready ou error, ou enregistrez un webhook signé sur les offres payantes au lieu d'interroger.

GET /api/v2/jobs/{id}mcp · pdf_to_markdown_get_job
3

Récupérez le Markdown

Téléchargez le résultat une fois prêt. Lisez truncated et pages pour savoir si un long document a été renvoyé partiellement.

GET /api/v2/jobs/{id}/downloadmcp · pdf_to_markdown_get_markdown
4

Supprimez / libérez l'emplacement

Libérez un emplacement une fois terminé. Supprimer des tâches en file ou en traitement est destructif : confirmez-le dans les clients destinés aux utilisateurs.

DELETE /api/v2/jobs/{id}mcp · pdf_to_markdown_delete_job
#!/usr/bin/env bash
# Requires curl and jq. Keep the key in your server environment.
set -euo pipefail
: "${P2M_API_KEY:?Set P2M_API_KEY}"
API="https://pdf2md.dev/api/v2"
PDF_URL="${PDF_URL:-https://example.com/document.pdf}"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
call() {
  local method="$1" path="$2" code
  shift 2
  code="$(curl --silent --show-error --max-time 30 \
    -X "$method" "$API$path" -H "Authorization: Bearer $P2M_API_KEY" \
    -D "$tmp/headers" -o "$tmp/body" -w '%{http_code}' "$@")"
  if [[ "$code" == 429 ]]; then
    awk 'tolower($1)=="retry-after:" {print "Rate limited; retry after " $2 " seconds"}' "$tmp/headers" >&2
    return 1
  fi
  [[ "$code" =~ ^2[0-9][0-9]$ ]] || { echo "HTTP $code" >&2; return 1; }
  cat "$tmp/body"
}
payload="$(jq -n --arg url "$PDF_URL" '{url:$url,options:{image_mode:"placeholder",ocr_lang:"en"}}')"
jid="$(call POST /jobs -H 'Content-Type: application/json' --data "$payload" | jq -er '.job_id')"
deadline=$((SECONDS + 1200))
while :; do
  job="$(call GET "/jobs/$jid")"
  status="$(jq -er '.status' <<<"$job")"
  case "$status" in
    ready) break ;;
    error|canceled|deleted) echo "Job ended: $status" >&2; exit 1 ;;
  esac
  (( SECONDS < deadline )) || { echo 'Polling deadline reached; the job may still run' >&2; exit 1; }
  sleep 3
done
call GET "/jobs/$jid/download" > document.md
if [[ "$(jq -r '.truncated // false' <<<"$job")" == true ]]; then
  echo 'Partial result; verify missing pages' >&2
fi

Erreurs. Les réponses utilisent des formes stables et des codes HTTP prévisibles (400 entrée incorrecte, 401 auth, 404 tâche inconnue, 409 aucun emplacement libre / slots_full, 413 trop volumineux, 429 débit limité). Le schéma complet se trouve dans le spec OpenAPI.

Plus d'endpoints de tâches

Créer depuis un fichier (multipart)POST /api/v2/jobs
Lister vos tâchesGET /api/v2/jobs
Création par lots (payant)POST /api/v2/jobs/batch

Create accepte un url JSON ou un file multipart, plus des champs facultatifs file_name, external_id, tags et callback_url / callback_secret pour un webhook par tâche. La création par lots est tout-ou-rien et doit tenir dans vos emplacements libres.

L'objet tâche

job_idstring
statusqueued · processing · ready · error
pages · output_sizeinteger
truncatedboolean
error_code · error_messagemotif (en cas d'erreur)
download_urlstring (quand ready)
external_id · tagsvos métadonnées
slot_usage · tiercontexte de quota

Compte et usage. Consultez votre offre, vos limites et votre usage à l'exécution avec GET /api/v2/me, /api/v2/limits et /api/v2/usage ; gérez les clés sur /api/v2/api-keys et les webhooks sur /api/v2/webhooks.

Démarrage rapide

Convertir un PDF en Markdown en Python

Les mêmes quatre appels depuis n'importe quel langage. Le voici avec requests. Pour un parcours complet pas à pas avec gestion des erreurs, consultez le tutoriel Python.

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")
Plus de recettes : envoi de fichier et Node

Créer depuis un fichier local (curl)

# multipart upload of a local PDF
curl -X POST https://pdf2md.dev/api/v2/jobs \
  -H "Authorization: Bearer p2m_…" \
  -F "[email protected]" \
  -F "file_name=document.pdf"

Node 18+ (fetch global)

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

La vérification de signature des webhooks est dans la section Webhooks ; la configuration du client MCP est dans la section MCP. Schéma complet : OpenAPI.

MCP hébergé

La conversion sous forme d'outils d'agent

Connectez un agent compatible à notre endpoint MCP géré. Les outils sont une fine couche au-dessus de l'API REST, donc chaque appel obéit aux mêmes emplacements, limites et conservation.

1

Pointez l'agent vers l'endpoint

JSON-RPC 2.0 sur Streamable HTTP avec votre clé d'API comme token bearer. Aucun serveur local à exécuter. Méthodes : initialize, tools/list, tools/call, ping.

POST https://pdf2md.dev/api/v2/mcp
2

Appelez les outils

Le même cycle de vie plus les limites, exposé sous forme de sept outils. Chacun respecte les scopes de la clé ; les réponses de tools/call incluent slot_usage et tier.

create_job_from_url · create_job_from_upload (jobs:create)list_jobs · get_job (jobs:read)get_markdown (jobs:download) · delete_job (jobs:delete)get_limits
3

Respectez les règles

Attendez ready avant d'utiliser la sortie ; confirmez avant de supprimer des tâches en file/en traitement ; gérez truncated et 429 Retry-After. (Les noms d'outils sont préfixés par pdf_to_markdown_.)

// MCP client config (hosted, no local process)
{
  "mcpServers": {
    "pdf2md": {
      "url": "https://pdf2md.dev/api/v2/mcp",
      "headers": {
        "Authorization": "Bearer p2m_…"
      }
    }
  }
}
OpenAPI et Custom GPT Actions

Importez le spec, obtenez un outil intégré

Nous publions deux specs : l'OpenAPI complet pour les développeurs, et un spec d'action réduit avec le sous-ensemble sûr et minimal pour les clients d'IA et les Custom GPT Actions de ChatGPT.

OpenAPI complet

Le contrat complet : chaque endpoint, paramètre, DTO et erreur. Générez des clients ou explorez-le dans vos outils.

Ouvrir le spec complet

Spec réduit pour Custom GPT

Un sous-ensemble minimal d'action (créer, statut, récupérer) pour les Custom GPT Actions de ChatGPT. Importez l'URL, définissez votre clé d'API comme auth, et votre GPT convertit les PDF nativement.

Ouvrir le spec réduit

Le spec réduit est une commodité pour les clients d'IA, pas une frontière de sécurité : la même auth, les mêmes scopes et limites s'appliquent que sur l'API complète.

Limites et limites de débit

Limites par offre, appliquées de la même façon à l'API et au MCP

Les limites proviennent de votre offre et s'appliquent à l'identique sur chaque surface. Les valeurs en direct sont sur la page des tarifs.

Offre gratuite (avec un compte)

Emplacements actifs (profondeur de file)3
Taille de PDF maximale10 MB
Budget de temps par document15 min
Conservation du résultat prêt1 heure

Les offres payantes augmentent les emplacements, la taille de fichier, le budget de temps, la conservation et les limites de débit, et ajoutent les webhooks et la création par lots. Comparer les offres →

Limites de débit et contre-pression

Limites de débit par offre. Les requêtes sont limitées en débit par clé ; si vous les dépassez, vous recevez 429 avec un en-tête Retry-After : temporisez et réessayez.
Pression sur les emplacements. Si tous les emplacements sont occupés, create renvoie 409. Libérez un emplacement avec delete, ou attendez qu'une tâche se termine.
Priorité sur les offres payantes. Les tâches payantes s'exécutent avec une priorité de file plus élevée sur un pool de conversion payant dédié, de sorte qu'elles n'attendent pas derrière le backlog gratuit.
Webhooks

Soyez notifié au lieu d'interroger

Sur les offres payantes, enregistrez un webhook signé (ou passez un callback_url par tâche) et nous vous faisons un POST à chaque événement terminal notable : job.ready, job.error, job.truncated et job.deleted. L'événement est une notification, pas une livraison : il ne transporte aucun contenu de document, donc récupérez le Markdown via l'API après l'avoir reçu.

1

Enregistrez un endpoint

Faites un POST d'une URL HTTPS (protégée contre le SSRF) et d'un filtre events facultatif. Le secret de signature whsec_… est renvoyé une seule fois. Ou définissez callback_url + callback_secret sur une tâche unique.

POST /api/v2/webhooksGET /api/v2/webhooks/deliveries
2

Recevez l'événement

Nous vous faisons un POST de JSON avec les en-têtes X-P2M-Event, X-P2M-Timestamp, X-P2M-Delivery et X-P2M-Signature.

3

Vérifiez, puis agissez

Recalculez la signature, accusez réception avec 2xx, et soyez idempotent (les livraisons peuvent réessayer avec backoff). Téléchargez ensuite le Markdown.

# delivery → your endpoint
X-P2M-Event: job.ready
X-P2M-Timestamp: 1718900000
X-P2M-Signature: sha256=9a8b7c…

{
  "event": "job.ready",
  "job": {
    "job_id": "job_9f3c…",
    "status": "ready",
    "pages": 24, "truncated": false,
    "download_url": "/api/v2/jobs/job_9f3c…/download"
  }
}

# verify (Python): signature = sha256= + hex(HMAC(secret, "ts.rawbody"))
import hmac, hashlib
def verify(secret, ts, raw_body, sig):
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body,
        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)
Prompts et sécurité

Instructions portables pour les agents

Insérez ces règles dans le system prompt d'un agent pour qu'il pilote correctement les outils et n'invente jamais de résultats.

Attendez ready

Ne revendiquez ni ne résumez jamais un résultat avant status=ready. Tant que c'est queued ou processing, continuez d'interroger ou attendez le webhook.

Confirmez les suppressions

Supprimer une tâche queued ou processing est destructif. Demandez à l'utilisateur avant d'appeler pdf_to_markdown_delete_job sur une tâche non terminée.

Gérez la troncature

Si truncated=true, dites à l'utilisateur que le document a été renvoyé partiellement jusqu'au budget de temps de l'offre, et proposez une offre supérieure ou de découper le fichier.

Respectez le 429

En cas de 429, attendez le nombre de secondes de Retry-After avant de réessayer. Ne martelez pas la file.

Libérez les emplacements

Supprimez les tâches terminées dont vous n'avez plus besoin pour ne pas épuiser vos emplacements.

Lisez la découverte

Partez de /llms.txt et du spec OpenAPI plutôt que de deviner les endpoints à partir de la prose.

Découverte lisible par machine

Tout ce dont un agent a besoin pour s'intégrer sans lire le code source : un fichier de capacités compact, un fichier de contexte détaillé et le spec OpenAPI.