Início rápido
Crie uma chave de API e envie um arquivo. Novas contas começam com 50 créditos grátis.
curl https://api.ocrrouter.ai/v1/ocr \
-H "Authorization: Bearer $OCRROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"file_url": "https://example.com/invoice.pdf",
"format": "markdown"
}'Requisição
POST https://api.ocrrouter.ai/v1/ocr com corpo JSON e cabeçalho Authorization: Bearer.
| model | string | Um ID de modelo como mistral/mistral-ocr, ou auto. |
| file_url | string | URL pública de um PDF ou imagem. Use um entre file_url, file_base64 ou file_id. |
| file_base64 | string | O arquivo em base64, até 20 MB. |
| file_id | string | ID retornado por POST /v1/files, para arquivos maiores. |
| format | string | markdown (padrão), json, text, html, csv, docx ou xlsx. |
| pages | string | Intervalo de páginas, por exemplo 1-5,8. O padrão são todas as páginas. |
| fallbacks | string[] | IDs de modelos para tentar, em ordem, se o primeiro modelo falhar. |
| route | string | Com model auto: quality (padrão), cheapest ou fastest. |
| filename | string | Nome opcional exibido no seu log de atividades. |
Outros endpoints:
GET /v1/modelslista todos os modelos, seus preços e disponibilidade. Não precisa de chave.POST /v1/filesrecebe um upload multipart com o campofilee retorna umfile_idválido por 24 horas.GET /v1/requests/:idretorna um resultado anterior. Adicione?format=com qualquer formato de saída para obtê-lo em outro formato.GET /v1/creditsretorna seu saldo e o uso desta chave.POST /v1/keys/temporaryretorna uma chave temporária com 50 créditos. Sem cadastro, uma por dia.
Formatos de saída
markdown
O documento completo em Markdown. Tabelas são tabelas no padrão GitHub, fórmulas são envolvidas em $...$ e páginas são separadas por <!-- page:N -->.
json
A mesma estrutura para todos os modelos: páginas, cada uma com blocos tipados. Os tipos de bloco são heading, paragraph, list, table, formula, image, header e footer. bbox, confidence e tamanho da página são null quando o modelo não os fornece, o que é o caso dos modelos disponíveis hoje.
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "json","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"pages": [{"index": 1,"width": null,"height": null,"blocks": [{"type": "heading","level": 1,"text": "Invoice INV-2041","bbox": null,"confidence": null},{"type": "paragraph","text": "Acme Supply Co.\n14 Harbour Street, Sydney NSW 2…","bbox": null,"confidence": null},{"type": "table","rows": [["Item", "Qty", "Unit price", "Amount"],["A4 paper, 5 reams", "4", "$24.00", "$96.00"]],"markdown": "| Item | Qty | Unit price | Amount |\n|---|---|-…","bbox": null,"confidence": null}]}],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}text, html, csv, docx, xlsx
A resposta em Markdown com um objeto output adicional contendo um arquivo: format, filename, mime_type, encoding e data. text, html e csv são strings UTF-8 (encoding: "utf8"); docx e xlsx são base64 (encoding: "base64"). csv e xlsx contêm as tabelas (uma planilha por tabela) ou as linhas de texto quando não houver tabelas. txt é aceito como sinônimo de text.
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "docx","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"markdown": "<!-- page:1 -->\n# Invoice INV-2041\n…","pages": [{ "index": 1, "markdown": "# Invoice INV-2041\n…" }],"output": {"format": "docx","filename": "invoice.docx","mime_type": "application/vnd.openxmlformats-officedocument.w…","encoding": "base64","data": "UEsDBBQAAAAIA…"},"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}Roteamento e fallbacks
Defina model como auto e nós escolheremos um modelo para cada documento. Use route para definir o critério: cheapest, fastest ou quality.
Adicione fallbacks para manter o serviço funcionando durante instabilidades. Se o primeiro modelo apresentar erro ou sofrer rate limit, o próximo será executado. A resposta indica qual modelo respondeu, e você paga apenas por ele.
{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}Créditos
Cada modelo tem um preço em créditos por página. $1 compra 1,000 créditos e eles não expiram. Toda resposta inclui usage.credits.
- Resultados com falha ou vazios são gratuitos.
- Enviar o mesmo arquivo para o mesmo modelo novamente é servido do cache de graça.
- Cada chave de API pode ter seu próprio limite de créditos.
Erros
Agentes, MCP e CLI
Agentes de código podem usar o OCRRouter sem etapa de cadastro. A CLI e o servidor MCP solicitam uma chave temporária com 50 créditos no primeiro uso e a salvam em ~/.ocrrouter/config.json. Defina OCRROUTER_API_KEY para usar sua própria chave.
# CLI
npx ocrrouter invoice.pdf --format markdown
# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcpUm resumo desta página legível por máquina está em /llms.txt.