API REST
Endpoints HTTPS com uma chave de API bearer. DTOs estáveis, erros previsíveis, criação idempotente.
Ver o ciclo de vidaUm ciclo de vida do trabalho previsível sobre uma API REST e um MCP hospedado equivalente: crie um trabalho, espere por ready, obtenha o Markdown, libere o espaço. A API e o MCP nunca ignoram os limites do produto.
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.
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.
Endpoints HTTPS com uma chave de API bearer. DTOs estáveis, erros previsíveis, criação idempotente.
Ver o ciclo de vidaUm endpoint gerenciado de Model Context Protocol que expõe a conversão como ferramentas de agente: uma camada fina sobre a mesma API.
Conectar MCPImporte um spec OpenAPI reduzido em um Custom GPT do ChatGPT para que ele possa converter PDF como ferramenta integrada.
Configurar a actionA 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.
Authorization: Bearer p2m_… em cada requisição.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.
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.
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.
Consulte o trabalho até ready ou error, ou registre um webhook assinado nos planos pagos em vez de consultar.
Baixe o resultado assim que estiver pronto. Leia truncated e pages para saber se um documento longo foi retornado em parte.
Libere um espaço quando terminar. Excluir trabalhos na fila ou em processamento é destrutivo: confirme isso em clientes voltados ao usuário.
#!/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
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.
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.
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.
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.
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")
# 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+. 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');
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.
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.
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.
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.
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_…"
}
}
}
}
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.
O contrato completo: cada endpoint, parâmetro, DTO e erro. Gere clientes ou explore-o nas suas ferramentas.
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.
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.
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.
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 →
429 com um cabeçalho Retry-After: recue e tente de novo.409. Libere um espaço com delete, ou espere um trabalho terminar.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.
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.
Fazemos POST de JSON com os cabeçalhos X-P2M-Event, X-P2M-Timestamp, X-P2M-Delivery e X-P2M-Signature.
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)
Coloque estas regras no system prompt de um agente para que ele conduza as ferramentas corretamente e nunca invente resultados.
Nunca reivindique nem resuma um resultado antes de status=ready. Enquanto estiver queued ou processing, continue consultando ou espere o webhook.
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.
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.
Diante de um 429, espere os segundos de Retry-After antes de tentar de novo. Não martele a fila.
Exclua os trabalhos finalizados que você não precisa mais para não esgotar seus espaços.
Comece por /llms.txt e o spec OpenAPI em vez de adivinhar endpoints a partir da prosa.
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.