OCRRouter

Documentação da API

Guias para os conceitos principais. Todos os endpoints e parâmetros estão na referência da API.

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.

modelstringUm ID de modelo como mistral/mistral-ocr, ou auto.
file_urlstringURL pública de um PDF ou imagem. Use um entre file_url, file_base64 ou file_id.
file_base64stringO arquivo em base64, até 20 MB.
file_idstringID retornado por POST /v1/files, para arquivos maiores.
formatstringmarkdown (padrão), json, text, html, csv, docx ou xlsx.
pagesstringIntervalo de páginas, por exemplo 1-5,8. O padrão são todas as páginas.
fallbacksstring[]IDs de modelos para tentar, em ordem, se o primeiro modelo falhar.
routestringCom model auto: quality (padrão), cheapest ou fastest.
filenamestringNome opcional exibido no seu log de atividades.

Outros endpoints:

  • GET /v1/models lista todos os modelos, seus preços e disponibilidade. Não precisa de chave.
  • POST /v1/files recebe um upload multipart com o campo file e retorna um file_id válido por 24 horas.
  • GET /v1/requests/:id retorna um resultado anterior. Adicione ?format= com qualquer formato de saída para obtê-lo em outro formato.
  • GET /v1/credits retorna seu saldo e o uso desta chave.
  • POST /v1/keys/temporary retorna 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.

200result
{"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.

200result
{"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

400A requisição está malformada ou o tipo de arquivo não é suportado.
401A chave de API está ausente ou foi revogada.
402Créditos insuficientes ou a chave atingiu seu limite de créditos.
413O arquivo é maior do que o limite para este modelo.
429Muitas requisições. Tente novamente após o tempo indicado no cabeçalho Retry-After.
502Todos os modelos na cadeia de fallback falharam. Você não foi cobrado.
503O modelo solicitado ainda não está conectado.

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 mcp

Um resumo desta página legível por máquina está em /llms.txt.

Dúvidas