Linha de comando

Converter PDF para Markdown com cURL

Sem linguagem de programação. Com curl e jq você converte um PDF para Markdown direto do terminal, de um Makefile, de um passo de CI ou de um cron. Copie a receita abaixo, defina sua chave e rode.

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 curta

Três curls e um loop de consulta

curl -X POST do PDF para /api/v2/jobs com sua chave, extraia o job_id com jq, faça um loop em /api/v2/jobs/{job_id} até o status ser ready, e então faça curl em /api/v2/jobs/{job_id}/download com -o para salvar o Markdown. É HTTP puro, então roda onde quer que uma shell rode, sem SDK e sem nada para compilar.

Como fazer

A receita de shell completa

Salve como convert.sh, chmod +x, e rode. Troque pela sua chave e pelo seu PDF.

#!/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

A opção -f faz o curl falhar diante de erros HTTP, e set -euo pipefail interrompe o script no primeiro problema, então uma execução quebrada nunca grava um arquivo vazio em silêncio.

Onde encaixa

Feito para automação

Como é um único script autocontido com um código de saída real, a receita se encaixa onde um programa completo seria exagero.

Pipelines de CI

Adicione como passo de build para converter PDFs de documentação em Markdown a cada commit. Uma conversão falha faz o passo falhar.

Jobs de cron

Agende para baixar e converter um relatório noturno, gravando o Markdown onde seu site de documentação ou seu pipeline espera.

Segredos, não literais

Mantenha a chave de API em um segredo de CI ou uma variável de ambiente e referencie-a no cabeçalho Authorization, nunca embutida no código.

Quer isso dentro de um app? Veja os tutoriais de Python, Node.js e Go.

Toda a API em uma página

Cada endpoint, campo e código de erro está no hub para desenvolvedores, com a especificação OpenAPI que você pode importar no Postman ou usar para gerar um cliente.

Além do bash

Outras shells e webhooks

A receita é bash, mas as três chamadas são só HTTP, então elas se portam para qualquer lugar onde o curl rode.

Windows e PowerShell

O curl vem com o Windows moderno, então as mesmas chamadas funcionam no PowerShell ou em um arquivo .cmd; você só ajusta o uso de aspas (o PowerShell prefere aspas simples em volta do JSON, ou use Invoke-RestMethod com um corpo de hashtable). Em um Makefile, em um passo de build de Dockerfile ou em um bloco run: do GitHub Actions, o script não muda.

Pule o loop de consulta

A consulta é a abordagem mais simples e serve para um arquivo ou alguns poucos. Para muitos arquivos, ou para evitar a espera por completo, registre um webhook e a API chama você de volta quando um job fica pronto, assim um script pode disparar conversões e processar resultados à medida que chegam em vez de ficar em um loop.

Seja qual for a shell, mantenha a chave fora do corpo do script: leia-a de uma variável de ambiente ou de um segredo de CI. E se você precisar inspecionar um resultado antes de salvar, canalize o download para um visualizador (curl ... | less) em vez de -o, já que o endpoint retorna texto Markdown puro.

Perguntas frequentes

Perguntas comuns

O que eu preciso para rodar a receita de cURL?

Só curl e jq. O curl faz as chamadas HTTP e o jq lê job_id e status das respostas JSON. Ambos estão disponíveis na maioria dos sistemas ou a uma instalação de pacote de distância.

Como converto um arquivo local com curl?

Use um envio multipart: curl -X POST /api/v2/jobs -F [email protected] com o cabeçalho Authorization, em vez do corpo JSON -d que carrega uma url.

Como uso isso em CI ou em um cron?

O script sai com código diferente de zero quando um job falha, então ele se encaixa em um passo de CI ou em um cron agendado. Guarde a chave de API como um segredo de CI ou uma variável de ambiente e passe-a no cabeçalho Authorization.

Dá para fazer sem jq?

O jq é a forma mais limpa de ler job_id e status, mas você também pode fazer o parsing do JSON com grep e sed se o jq não estiver disponível. O jq é recomendado pela confiabilidade.

O que o cabeçalho Idempotency-Key faz?

Enviar a mesma Idempotency-Key em um create repetido retorna o mesmo job em vez de iniciar uma conversão duplicada, o que é útil quando um passo de CI instável roda de novo.