Em resumo

Duas superfícies, um motor

Escolha a integração que se encaixa. Ambas chamam o mesmo motor de conversão e obedecem aos mesmos espaços, limites e retenção.

API REST

Endpoints HTTPS com uma chave de API bearer. DTOs estáveis, erros previsíveis, criação idempotente.

Ver o ciclo de vida

MCP hospedado

Um endpoint gerenciado de Model Context Protocol que expõe a conversão como ferramentas de agente: uma camada fina sobre a mesma API.

Conectar MCP

Custom GPT Actions

Importe um spec OpenAPI reduzido em um Custom GPT do ChatGPT para que ele possa converter PDF como ferramenta integrada.

Configurar a action

Autenticação

Chaves de API bearer sobre HTTPS

A API e o MCP usam chaves de API bearer, distintas da via assinada por dispositivo que a extensão do Chrome usa. É necessária uma conta gratuita do Google para gerar chaves.

Obtenha uma chave

Entre com o Google (conta gratuita).
Gere uma chave de API na sua conta; ela é mostrada uma única vez.
Envie-a como Authorization: Bearer p2m_… em cada requisição.
As chaves são segredos: guarde-as no lado do servidor, rotacione e revogue quando quiser.

Padrões honestos

Chaves, não senhas. A extensão permanece anônima e assinada por dispositivo; as chaves de API/MCP são uma credencial separada, vinculada à conta.

Apenas HTTPS. Envie sempre as chaves sobre TLS; nunca embuta uma chave em código do lado do cliente que chega aos usuários.

Criação idempotente. Uma Idempotency-Key opcional na criação permite repetir com segurança sem trabalhos duplicados.

Scopes. Cada chave de API carrega scopes: jobs:create, jobs:read, jobs:download, jobs:delete (os padrões), mais settings:read / settings:write. Crie chaves de privilégio mínimo; tanto a API REST quanto as ferramentas MCP aplicam os scopes da chave.

API REST

Crie um trabalho, espere, obtenha o Markdown, limpe o espaço

Um ciclo de vida previsível, duas formas de conduzi-lo: chame a API REST a partir do seu próprio código, ou use as ferramentas equivalentes do MCP hospedado. Nunca reivindique um resultado antes de status=ready.

API REST MCP hospedado

1

Crie o trabalho

Faça POST de uma URL de PDF ou envie bytes. Você recebe de volta um id de trabalho e um espaço. Idempotency-Key é respeitado, mas opcional.

POST /api/v2/jobsmcp · pdf_to_markdown_create_job_from_url

2

Consulte o status

Consulte o trabalho até ready ou error, ou registre um webhook assinado nos planos pagos em vez de consultar.

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

3

Obtenha o Markdown

Baixe o resultado assim que estiver pronto. Leia truncated e pages para saber se um documento longo foi retornado em parte.

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

4

Exclua / limpe o espaço

Libere um espaço quando terminar. Excluir trabalhos na fila ou em processamento é destrutivo: confirme isso em clientes voltados ao usuário.

DELETE /api/v2/jobs/{id}mcp · pdf_to_markdown_delete_job

# 1. create a job from a PDF URL
curl -X POST https://pdf2md.dev/api/v2/jobs \
  -H "Authorization: Bearer p2m_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report.pdf"}'
# → { "job_id": "job_9f3c…", "status": "queued" }

# 2. poll status
curl https://pdf2md.dev/api/v2/jobs/job_9f3c… \
  -H "Authorization: Bearer p2m_…"
# → { "status": "ready", "pages": 24, "truncated": false }

# 3. fetch the Markdown
curl https://pdf2md.dev/api/v2/jobs/job_9f3c…/download \
  -H "Authorization: Bearer p2m_…"

# 4. free the slot
curl -X DELETE https://pdf2md.dev/api/v2/jobs/job_9f3c… \
  -H "Authorization: Bearer p2m_…"

Erros. As respostas usam formas estáveis e códigos HTTP previsíveis (400 entrada inválida, 401 auth, 404 trabalho desconhecido, 409 sem espaço livre / slots_full, 413 grande demais, 429 limite de taxa). O esquema completo está no spec OpenAPI.

Mais endpoints de trabalhos

Criar a partir de arquivo (multipart)POST /api/v2/jobs

Listar seus trabalhosGET /api/v2/jobs

Criar em lote (pago)POST /api/v2/jobs/batch

Create aceita um url JSON ou um file multipart, mais file_name, external_id, tags opcionais e callback_url / callback_secret para um webhook por trabalho. A criação em lote é tudo-ou-nada e deve caber nos seus espaços livres.

O objeto do trabalho

job_idstring

statusqueued · processing · ready · error

pages · output_sizeinteger

truncatedboolean

error_code · error_messagemotivo (quando error)

download_urlstring (quando ready)

external_id · tagsseus metadados

slot_usage · tiercontexto de cota

Conta e uso. Consulte seu plano, limites e uso em tempo de execução com GET /api/v2/me, /api/v2/limits e /api/v2/usage; gerencie chaves em /api/v2/api-keys e webhooks em /api/v2/webhooks.

Início rápido

Converta um PDF para Markdown em Python

As mesmas quatro chamadas a partir de qualquer linguagem. Aqui com requests. Para um passo a passo completo com tratamento de erros, veja o tutorial de Python.

# pip install requests
import time, requests

API = "https://pdf2md.dev/api/v2"
H = {"Authorization": "Bearer p2m_…"}

# 1. create a job from a PDF URL (or post a file with files={"file": ...})
job = requests.post(f"{API}/jobs", headers=H,
    json={"url": "https://example.com/report.pdf"}).json()
jid = job["job_id"]

# 2. poll until ready (or register a webhook instead)
while True:
    j = requests.get(f"{API}/jobs/{jid}", headers=H).json()
    if j["status"] in ("ready", "error"):
        break
    time.sleep(3)

# 3. download the Markdown
md = requests.get(f"{API}/jobs/{jid}/download", headers=H).text
print(md)

Mais receitas: envio de arquivos e Node

Criar a partir de um arquivo 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)

// create from URL, poll, download
const API = "https://pdf2md.dev/api/v2";
const H = { Authorization: "Bearer p2m_…" };

let job = await (await fetch(`${API}/jobs`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/report.pdf" })
})).json();

while (job.status === "queued" || job.status === "processing") {
  await new Promise(s => setTimeout(s, 2000));
  job = await (await fetch(`${API}/jobs/${job.job_id}`, { headers: H })).json();
}

if (job.status === "ready") {
  const md = await (await fetch(`${API}/jobs/${job.job_id}/download`, { headers: H })).text();
  console.log(md);
}

A verificação de assinatura de webhooks está na seção Webhooks; a configuração do cliente MCP está na seção MCP. Esquema completo: OpenAPI.

MCP hospedado

A conversão como ferramentas de agente

Conecte um agente compatível ao nosso endpoint MCP gerenciado. As ferramentas são uma camada fina sobre a API REST, então cada chamada obedece aos mesmos espaços, limites e retenção.

1

Aponte o agente para o endpoint

JSON-RPC 2.0 sobre Streamable HTTP com sua chave de API como token bearer. Sem servidor local para executar. Métodos: initialize, tools/list, tools/call, ping.

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

2

Chame as ferramentas

O mesmo ciclo de vida mais os limites, expostos como sete ferramentas. Cada uma respeita os scopes da chave; as respostas de tools/call incluem slot_usage e 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

Respeite as regras

Espere por ready antes de usar a saída; confirme antes de excluir trabalhos na fila/em processamento; trate truncated e 429 Retry-After. (Os nomes de ferramenta levam o prefixo pdf_to_markdown_.)

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

OpenAPI e Custom GPT Actions

Importe o spec, obtenha uma ferramenta integrada

Publicamos dois specs: o OpenAPI completo para desenvolvedores, e um spec de action reduzido com o subconjunto seguro e mínimo para clientes de IA e Custom GPT Actions do ChatGPT.

OpenAPI completo

O contrato completo: cada endpoint, parâmetro, DTO e erro. Gere clientes ou explore-o nas suas ferramentas.

Abrir o spec completo

Spec reduzido para Custom GPT

Um subconjunto mínimo de action (criar, status, obter) para Custom GPT Actions do ChatGPT. Importe a URL, defina sua chave de API como auth, e seu GPT converte PDF de forma nativa.

Abrir o spec reduzido

O spec reduzido é uma conveniência para clientes de IA, não uma fronteira de segurança: aplicam-se a mesma auth, scopes e limites que na API completa.

Limites e limites de taxa

Limites por plano, aplicados igualmente a API e MCP

Os limites vêm do seu plano e se aplicam de forma idêntica em cada superfície. Os valores ao vivo estão na página de preços.

Plano gratuito (com uma conta)

Espaços ativos (profundidade da fila)3

Tamanho máximo de PDF10 MB

Orçamento de tempo por documento15 min

Retenção do resultado pronto1 hora

Os planos pagos ampliam espaços, tamanho de arquivo, orçamento de tempo, retenção e limites de taxa, e adicionam webhooks e criação em lote. Comparar planos →

Limites de taxa e contrapressão

Limites de taxa por plano. As requisições são limitadas por chave; se você os exceder, recebe 429 com um cabeçalho Retry-After: recue e tente de novo.

Pressão de espaços. Se todos os espaços estiverem ocupados, create retorna 409. Libere um espaço com delete, ou espere um trabalho terminar.

Prioridade nos pagos. Os trabalhos pagos rodam com maior prioridade de fila em um pool de conversão pago dedicado, então não esperam atrás do backlog gratuito.

Webhooks

Seja avisado em vez de consultar

Nos planos pagos, registre um webhook assinado (ou passe um callback_url por trabalho) e fazemos POST para você em cada evento terminal notável: job.ready, job.error, job.truncated e job.deleted. O evento é uma notificação, não uma entrega: ele não leva conteúdo do documento, então obtenha o Markdown pela API depois de recebê-lo.

1

Registre um endpoint

Faça POST de uma URL HTTPS (com proteção SSRF) e um filtro events opcional. O segredo de assinatura whsec_… é retornado uma única vez. Ou defina callback_url + callback_secret em um único trabalho.

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

2

Receba o evento

Fazemos POST de JSON com os cabeçalhos X-P2M-Event, X-P2M-Timestamp, X-P2M-Delivery e X-P2M-Signature.

3

Verifique, depois aja

Recalcule a assinatura, confirme com 2xx, e seja idempotente (as entregas podem repetir com backoff). Depois baixe o 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 e segurança

Instruções portáteis para agentes

Coloque estas regras no system prompt de um agente para que ele conduza as ferramentas corretamente e nunca invente resultados.

Espere por ready

Nunca reivindique nem resuma um resultado antes de status=ready. Enquanto estiver queued ou processing, continue consultando ou espere o webhook.

Confirme as exclusões

Excluir um trabalho queued ou processing é destrutivo. Pergunte ao usuário antes de chamar pdf_to_markdown_delete_job em um trabalho não finalizado.

Trate a truncagem

Se truncated=true, diga ao usuário que o documento foi retornado em parte até o orçamento de tempo do plano, e ofereça um plano superior ou dividir o arquivo.

Respeite o 429

Diante de um 429, espere os segundos de Retry-After antes de tentar de novo. Não martele a fila.

Limpe espaços

Exclua os trabalhos finalizados que você não precisa mais para não esgotar seus espaços.

Leia a descoberta

Comece por /llms.txt e o spec OpenAPI em vez de adivinhar endpoints a partir da prosa.

Descoberta legível por máquinas

Tudo o que um agente precisa para integrar sem ler o código-fonte: um arquivo compacto de capacidades, um arquivo de contexto detalhado e o spec OpenAPI.

llms.txt llms-full.txt OpenAPI

Crie com a API de PDF para Markdown

Duas superfícies, um motor

API REST

MCP hospedado

Custom GPT Actions

Chaves de API bearer sobre HTTPS

Obtenha uma chave

Padrões honestos

Crie um trabalho, espere, obtenha o Markdown, limpe o espaço

Crie o trabalho

Consulte o status

Obtenha o Markdown

Exclua / limpe o espaço

Mais endpoints de trabalhos

O objeto do trabalho

Converta um PDF para Markdown em Python

Criar a partir de um arquivo local (curl)

Node 18+ (fetch global)

A conversão como ferramentas de agente

Aponte o agente para o endpoint

Chame as ferramentas

Respeite as regras

Importe o spec, obtenha uma ferramenta integrada

OpenAPI completo

Spec reduzido para Custom GPT

Limites por plano, aplicados igualmente a API e MCP

Plano gratuito (com uma conta)

Limites de taxa e contrapressão

Seja avisado em vez de consultar

Registre um endpoint

Receba o evento

Verifique, depois aja

Instruções portáteis para agentes

Espere por ready

Confirme as exclusões

Trate a truncagem

Respeite o 429

Limpe espaços

Leia a descoberta

Descoberta legível por máquinas