Converter PDFs para Markdown em lote
Tem uma pasta de relatórios, artigos ou faturas? Converta todos com a API REST: um pequeno job por arquivo, iterado sobre o seu conjunto, com retentativas seguras por idempotência para que uma reexecução nunca duplique o trabalho.
Um lote são muitos jobs pequenos
A API converte um PDF por job: criar, consultar, baixar. Para converter muitos, você executa esse fluxo uma vez por arquivo em um loop, com duas adições que tornam um lote confiável. Uma Idempotency-Key por arquivo significa que uma reexecução após uma queda retoma de onde parou em vez de refazer o trabalho concluído. Um pequeno limite de concorrência mantém várias conversões em andamento sem sobrecarregar a API. Essa mesma forma escala de dez arquivos a milhares.
Converta uma pasta inteira
Um loop de shell mínimo sobre cada PDF de um diretório. Troque pela sua chave.
API="https://pdf2md.dev/api/v2"
AUTH="Authorization: Bearer p2m_your_key"
for pdf in *.pdf; do
# o nome do arquivo como Idempotency-Key: uma reexecução reutiliza o mesmo job
JID=$(curl -fsS -X POST "$API/jobs" -H "$AUTH" \
-H "Idempotency-Key: $pdf" -F file=@"$pdf" | jq -r .job_id)
until [ "$(curl -fsS "$API/jobs/$JID" -H "$AUTH" | jq -r .status)" = "ready" ]; do
sleep 3
done
curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o "${pdf%.pdf}.md"
echo "convertido $pdf"
done
Esta versão é sequencial por clareza. Para volume real, converta vários arquivos de uma vez com um pool de workers e troque a consulta por webhooks, assim você é avisado à medida que cada job termina.
De uma pasta a um pipeline
Concorrência
Converta vários arquivos de uma vez com um pool de workers limitado. Comece com cerca de cinco em andamento e ajuste ao seu plano.
Retentativas idempotentes
Uma chave estável por arquivo (nome ou hash do conteúdo) torna uma reexecução segura, então um lote pela metade retoma de forma limpa.
Webhooks
Para milhares de arquivos, deixe os webhooks avisarem você quando cada job está pronto em vez de consultar todos.
Lidar com falhas em um lote
Em uma execução real, alguns arquivos estarão protegidos por senha, corrompidos ou simplesmente grandes demais. O objetivo é deixar o lote terminar e informar o que foi pulado, não parar no primeiro arquivo ruim.
Pule e registre, não pare
Quando um job retornar com status: error, registre o nome do arquivo e seu error_code em um log e siga em frente. No fim você tem um conjunto limpo de arquivos Markdown mais uma lista curta dos que precisam de atenção, em vez de um lote que morreu no meio.
Retome com segurança
Como cada create usa o nome do arquivo (ou um hash do conteúdo) como sua Idempotency-Key, reexecutar o lote inteiro é seguro: os arquivos concluídos retornam o job existente, e só os que falharam ou não foram processados fazem trabalho real. Um job noturno pode reexecutar a mesma pasta sem refazer tudo.
Mais dois detalhes mantêm as execuções grandes organizadas. Escreva cada resultado ao lado da origem (report.pdf vira report.md) para que o mapeamento seja óbvio, e verifique a flag truncated em cada job, já que um documento muito longo pode voltar como resultado parcial que atingiu o orçamento de tempo. No plano gratuito os limites de espaços e tamanho são mais baixos, então um lote grande é um bom motivo para migrar a um plano pago, que amplia a concorrência, o tamanho de arquivo e a cota mensal de páginas.
Alimentando uma base de conhecimento?
Um lote de PDFs vira uma pasta de Markdown limpo, pronta para fazer chunking e embedding. Consulte o guia de RAG para transformar essa saída em contexto recuperável.
Perguntas comuns
Como converto muitos PDFs de uma vez?
Execute o fluxo de criar, consultar e baixar por arquivo em um loop. Use uma Idempotency-Key por arquivo para que uma reexecução não duplique o trabalho, e um pequeno limite de concorrência para ser gentil com a API.
Existe um único endpoint em massa?
A conversão é por job, então um lote são muitos jobs. O mesmo loop escala de alguns poucos arquivos a milhares; adicione concorrência e webhooks para execuções grandes.
Como evito reconverter arquivos numa retentativa?
Passe uma Idempotency-Key estável ao criar, por exemplo o nome do arquivo ou um hash do conteúdo. A mesma chave retorna o mesmo job em vez de iniciar uma conversão duplicada.
Quantos posso executar em paralelo?
Comece com um pool pequeno, por exemplo cinco, e ajuste. O plano gratuito tem limites de espaços mais baixos; os planos pagos ampliam os espaços e a vazão.
Posso usar webhooks em vez de consultar cada job?
Sim. Para lotes grandes, os webhooks avisam você à medida que cada job termina, o que escala melhor do que consultar milhares de jobs. Consulte o hub para desenvolvedores.