Tutorial de Python

Converter PDF em Markdown no Python

Um tutorial passo a passo usando a API REST: obtenha uma chave, crie um job, consulte e baixe Markdown limpo, com um exemplo completo e copiável e tratamento de erros como deve ser.

Conferir o resultado antes de usar

Use a especificação OpenAPI atual. Confira erros HTTP, estados, prazo máximo de espera e truncated antes de baixar. Guarde as chaves API no servidor.

Processamento no servidor e retenção temporária. Confira números e erros OCR no original.

Escolher as configurações do PDF

Resposta breve

Uma chave, três chamadas

Para converter um PDF em Markdown no Python você chama uma pequena API REST com uma chave bearer: POST /api/v2/jobs para criar um job, GET /api/v2/jobs/{id} para consultar até ficar pronto e depois GET /api/v2/jobs/{id}/download para o Markdown. Não há nada para hospedar nem uma biblioteca pesada para instalar, apenas requests. O mesmo ciclo de vida é exposto como um MCP hospedado para agentes, e a saída é o mesmo Markdown que a extensão e o app web produzem, então você pode prototipar no navegador e depois automatizar com confiança.

Como fazer

Configure em quatro passos

1

Obtenha uma chave de API

Entre com uma conta Google gratuita e crie uma chave de API na sua conta; ela é exibida uma única vez. Envie-a como Authorization: Bearer p2m_your_key.

2

Crie um job

Faça POST da URL do PDF (ou dos bytes enviados) em /api/v2/jobs. Você recebe um id de job e um status.

3

Consulte até ready

Faça GET /api/v2/jobs/{id} até status ser ready ou error.

4

Baixe o Markdown

Faça GET /api/v2/jobs/{id}/download para o texto Markdown. Respeite truncated e pages.

Exemplo completo

O script de Python completo

Biblioteca padrão mais requests. Crie a partir de uma URL de PDF, consulte e depois salve o 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")

Enviar um arquivo local em vez de uma URL? Faça POST dos bytes como multipart/form-data com um campo file no mesmo endpoint. As formas completas da requisição e da resposta estão na especificação OpenAPI.

Para converter muitos PDFs, crie um job por arquivo e consulte-os em paralelo até o seu limite de espaços (3 no plano gratuito, mais nos pagos). Mantenha um Idempotency-Key distinto por arquivo para que as novas tentativas nunca dupliquem trabalho, e recue diante de um 429 usando o cabeçalho Retry-After.

Deixe robusto

Erros, novas tentativas e webhooks

Leia o código de erro

Um job que falha retorna status: error com um error_code legível por máquina (processing_timeout ou conversion_failed) e um error_message seguro: ramifique pelo código, não pelo texto.

Trate truncated

Um documento longo pode voltar ready com truncated=true. Verifique a marca e divida o arquivo ou use um orçamento pago maior.

Idempotency-Key

Envie um cabeçalho Idempotency-Key para que um create repetido retorne o mesmo job em vez de duplicar trabalho.

Webhooks em vez de consulta

Nos planos pagos, registre um webhook ou passe callback_url e receba um POST em ready/error em vez de consultar.

Respeite o 429

Diante de um 429, espere os segundos de Retry-After antes de tentar de novo; não sature a fila.

Mantenha as chaves no servidor

A chave é um segredo: guarde-a no servidor, envie por TLS, e rotacione-a ou revogue-a quando quiser.

Outras linguagens

Não usa Python? As mesmas três chamadas

É uma API HTTPS simples, então qualquer linguagem funciona. O mesmo criar / consultar / baixar em 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');

Prefere ferramentas de agente ou RAG?

O mesmo ciclo de vida é um MCP hospedado para ChatGPT, Claude e frameworks de agentes. Para ingestão e chunking, consulte o guia de RAG.

Perguntas frequentes

Perguntas comuns

Como converto um PDF em Markdown no Python?

Chame a API REST com uma chave bearer: faça POST do PDF em /api/v2/jobs, consulte GET /api/v2/jobs/{id} até ready e depois faça GET de /download para o Markdown. O exemplo completo com requests está acima.

Preciso de uma chave de API?

Sim, para a API. Uma conta Google gratuita permite criar uma chave e usar o MCP hospedado. A extensão do navegador e o app web continuam anônimos e não precisam de chave.

Como trato erros e tempos de espera?

Um job que falha retorna status: error com um error_code legível por máquina (processing_timeout ou conversion_failed) e um error_message seguro. Um documento longo pode voltar ready com truncated=true; verifique essa marca.

Posso evitar a consulta?

Nos planos pagos, registre um webhook ou passe callback_url ao criar o job, e o serviço faz POST para você em ready ou error para que você não precise consultar.

Funciona com Node ou outras linguagens?

Sim. É uma API HTTPS simples, então qualquer linguagem funciona. Acima há um exemplo curto em Node, e o contrato completo está na especificação OpenAPI.

Como converto um arquivo local em vez de uma URL?

Faça POST dos bytes do arquivo como multipart/form-data com um campo file em /api/v2/jobs, em vez de um corpo JSON com url. Os passos de consultar e baixar são idênticos.

Posso converter muitos PDFs de uma vez?

Crie um job por arquivo e consulte-os em paralelo até o seu limite de espaços (3 no plano gratuito, mais nos pagos). Os planos pagos adicionam um endpoint de criação em lote e webhooks para que você não consulte nada.

A saída é a mesma da extensão e do app web?

Sim. Cada superfície usa o mesmo motor de conversão, então a API retorna o mesmo Markdown que você obteria no navegador.

É gratuito?

O plano gratuito oferece 3 espaços, arquivos de 10 MB, um orçamento de tempo de 15 minutos e retenção de 1 hora. Os planos pagos ampliam todos os limites e adicionam webhooks e criação em lote.