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.
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.
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.
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.
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 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.