API
API de conversão de documentos
A API de conversão de documentos é uma API HTTPS que aceita um arquivo, uma URL ou HTML em uma única chamada POST /v1/convert/{name} e devolve Markdown.
O teste anônimo aceita arquivos de até 10 MB e 25 páginas, com 3 conversões por IP e hora e 10 ao dia. O Lite começa em $20 por mês com arquivos de até 100 MB. O Pro custa $50 por mês; o Max custa $100 por mês.
- Uma chamada POST /v1/convert/{name} por arquivo, URL ou texto embutido
- Markdown na resposta em 60 segundos, ou uma conversão para consultar
- O mesmo motor de conversão do aplicativo web
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
-H "x-api-key: mdai_…" \
-F file=@nist-cswp-29-csf-2.0.pdf
# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
-H "x-api-key: mdai_…" \
-H "content-type: application/json" \
-d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'
# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
-H "x-api-key: mdai_…"Como funciona a API de conversão de documentos
Três passos da chave ao Markdown. Cada chamada espera até 60 segundos e responde com o resultado; requisições mais longas ou com vários arquivos devolvem 202 e uma conversão para consultar em vez de manter a conexão aberta.
Crie uma chave de API
Crie uma chave em Configurações → Desenvolvedores (precisa de uma assinatura ativa) e envie-a no cabeçalho x-api-key.
POST /v1/convert/{name}
Envie um arquivo, uma URL pública ou texto embutido para o endpoint daquele formato. Um tipo de entrada por chamada.
Use o Markdown
Leia a saída da resposta ou aguarde /v1/conversions/{id} depois de um 202.
Resposta e webhooks
A resposta abaixo ilustra o contrato da API usando a saída verificada de um analisador DOCX; o ID da conversão é um marcador de posição. Uma conversão concluída devolve o Markdown com os créditos que custou. Um 202 traz um cabeçalho Location para a conversão; consulte com ?wait=, transmita seus eventos ou deixe um webhook avisar quando terminar.
{
"id": "cnv_3f7c…",
"object": "conversion",
"name": "word",
"status": "completed",
"files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
"usage": { "credits_charged": 1 }
}POST https://your-app.example.com/webhooks
{
"type": "conversion.completed",
"data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}Assine conversion.completed e conversion.failed para poder reagir no momento em que uma conversão longa ou com vários arquivos termina, em vez de fazer polling. As entregas são assinadas com cabeçalhos do Standard Webhooks.
API de análise de documentos e API de Markdown
As equipes buscam uma API de análise de documentos quando precisam extrair estrutura dos arquivos, e uma API de Markdown quando a saída precisa chegar a um prompt ou a um repositório. As duas expressões descrevem este serviço. As páginas específicas de formato, como a api de pdf para markdown e a api de url para markdown, são âncoras para esses conversores: usam os mesmos endpoints /v1/convert/{name}.
Endpoints de conversão
POST /v1/convert/{name} —um endpoint por formato— aceita um arquivo, uma URL ou texto e devolve Markdown, texto, HTML ou saída por página.
Chaves de API
Chaves por conta enviadas com o cabeçalho x-api-key, para que a conversão caiba em qualquer servidor ou script.
Vários arquivos e webhooks
Envie muitos arquivos para uma mesma chamada de conversão e receba uma única conversão; os webhooks informam cada conversion.completed ou conversion.failed.
Markdown Render
POST /v1/convert/markdown/html ou /markdown/text converte Markdown de volta para HTML ou texto simples sem custo em créditos.
Casos de uso
Onde as equipes integram
Ingestão para RAG
Converta documentos dentro de jobs de ingestão antes de dividir em blocos e incorporar.
Agentes de IA
Deixe os agentes converterem arquivos arbitrários em texto limpo no meio do processo.
Fluxos de conteúdo
Leve Markdown para um CMS, um site de documentação ou uma base de conhecimento automaticamente.
Ferramentas internas
Adicione conversão de documentos aos produtos e ferramentas internas que você já usa.
Autenticação, uso e limites
- As chaves de API pertencem à sua conta, funcionam só em /v1 e são enviadas no cabeçalho x-api-key; a conta precisa de uma assinatura Lite, Pro ou Max ativa
- O uso consome os mesmos créditos do aplicativo web: as páginas padrão e de OCR custam 1 crédito por página
- Os limites de requisições por plano são Lite 20, Pro 40 e Max 60 requisições por minuto
- Idempotency-Key em cada chamada POST /v1/convert/{name}, para que uma nova tentativa nunca cobre duas vezes
- Todos os endpoints v1, os campos da requisição e da resposta estão documentados na referência da API gerada; as falhas usam problem+json com uma URI type que resolve para a página do código de erro correspondente
Guia
Lidar com a conclusão
Lide tanto com a conclusão em linha quanto com o processamento assíncrono em um cliente da API de conversão de documentos. Um envio bem-sucedido pode devolver um resultado já concluído, enquanto o HTTP 202 indica que o trabalho continua depois da resposta. Guarde o identificador da conversão e use o endpoint documentado de Location ou de status da conversão antes de ler as saídas. Não indexe direto em uma suposta primeira saída só porque a requisição HTTP funcionou. Uma conversão concluída também pode conter falhas no nível do arquivo, então inspecione cada arquivo em uma requisição com várias origens. Guarde contexto suficiente para conectar cada resultado devolvido à origem que sua aplicação enviou. Assim você evita que uma conversão lenta ou uma falha parcial virem em silêncio um documento vazio dentro do seu sistema.
Limites de requisição versus limites do plano
A API de conversão de documentos aplica limites tanto às requisições quanto às contas. Uma requisição multipart pode incluir até 100 arquivos com um limite combinado de 100 MB. Uma requisição por URL aceita até 20 origens. Sua assinatura controla separadamente créditos, armazenamento, limites por arquivo e concorrência. Um arquivo permitido pelo seu plano Pro pode ser grande demais para uma única requisição multipart; use nesse caso o fluxo de upload em partes documentado. Não contorne uma requisição rejeitada presumindo que o plano mais alto elimina os limites de transporte. Leia o erro e use o método de entrada previsto para o tamanho da origem.
Preservar o contexto da origem
Guarde seu próprio identificador de origem junto ao identificador da conversão, para que um resultado possa ser rastreado até o job que o enviou. O campo metadata da API carrega dados fornecidos por quem chama; ele não é uma promessa de extrair títulos de página, autores ou datas de publicação. Se sua aplicação precisa desses dados, colete-os e verifique-os em um passo separado adequado. Antes de ler seu texto, verifique se uma saída é devolvida em linha ou por meio de um artefato referenciado, e conserve o documento original quando seu fluxo precisar de uma trilha de auditoria. Uma API de conversão de documentos prepara o conteúdo para a etapa seguinte, enquanto sua aplicação continua responsável por associar esse conteúdo à origem e por decidir por quanto tempo conservá-lo.
Testar antes do lançamento
Teste mais de um arquivo pequeno bem-sucedido antes de integrar a API de conversão de documentos em um fluxo de produção. Inclua uma entrada que exija conclusão assíncrona, um arquivo incompatível ou danificado, uma requisição com várias origens e resultados mistos, e uma resposta que seu cliente deva tratar como erro de limite. Verifique que sua própria lógica de nova tentativa não reenvie arquivos corretos após uma falha parcial. Guarde as credenciais da API no seu servidor e evite colocá-las em código de navegador ou em exemplos públicos. Revise o Markdown real dos tipos de origem representativos antes de avaliar a recuperação ou o comportamento do modelo posterior. Um cliente que lida bem com erros de transporte ainda precisa de verificações no nível do conteúdo para provar que os documentos resultantes são úteis.
FAQ
Perguntas sobre a API de documento para Markdown
Como me autentico na API de conversão de documentos?
Crie uma chave de API na sua conta e envie-a no cabeçalho `x-api-key`. As chaves são restritas à sua conta.
Qual é o fluxo real de conversão?
POST /v1/convert/{name} com um arquivo, uma URL pública ou texto. O Markdown volta na mesma resposta quando o documento termina dentro da janela de espera; caso contrário, você recebe 202 e uma conversão na qual esperar com GET /v1/conversions/{id}?wait=.
A conversão é síncrona?
Por padrão, até a janela de espera: POST /v1/convert/{name} espera um resultado e o devolve em linha, ou devolve 202 com um Location quando a conversão não consegue terminar a tempo. Envie Prefer: respond-async para pular a espera.
A que eventos posso me inscrever?
Os webhooks de saída aceitam conversion.completed e conversion.failed, para você reagir assim que uma conversão termina em vez de fazer polling.
Quais planos incluem acesso à API?
O acesso à API está disponível nos planos pagos. Consulte a página de preços para ver os limites e créditos atuais de cada plano.
Como o uso da API é cobrado?
As conversões por API são descontadas do mesmo saldo de créditos do aplicativo web. As páginas padrão e as de OCR custam 1 crédito por página.
Onde encontro uma api de pdf para markdown ou uma api de url para markdown?
Essas expressões são páginas de formato, não hosts adicionais. Use as notas da api de pdf para markdown em /pdf-to-markdown e as da api de url para markdown em /url-to-markdown, e depois chame os mesmos endpoints de upload e conversão documentados aqui.
Quais são os limites de requisições das chaves de API?
As requisições são limitadas por conta: Lite 20, Pro 40 e Max 60 requisições por minuto.
Converta seu primeiro arquivo para Markdown.
Teste de graça: não precisa se cadastrar.