Guía rápida
Crea una clave de API y envía un archivo. Las cuentas nuevas empiezan con 50 créditos gratis.
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"
}'Solicitud
POST https://api.ocrrouter.ai/v1/ocr con un cuerpo JSON y un encabezado Authorization: Bearer.
| model | string | El ID de un modelo como mistral/mistral-ocr, o auto. |
| file_url | string | URL pública de un PDF o imagen. Usa file_url, file_base64 o file_id. |
| file_base64 | string | El archivo en base64, hasta 20 MB. |
| file_id | string | ID devuelto por POST /v1/files, para archivos más grandes. |
| format | string | markdown (predeterminado), json, text, html, csv, docx o xlsx. |
| pages | string | Rango de páginas, por ejemplo 1-5,8. Por defecto incluye todas. |
| fallbacks | string[] | IDs de modelos a probar, en orden, si el primero falla. |
| route | string | Con el modelo auto: quality (predeterminado), cheapest o fastest. |
| filename | string | Nombre opcional que se muestra en tu historial de actividad. |
Otros endpoints:
GET /v1/modelslista todos los modelos, su precio y disponibilidad. No requiere clave.POST /v1/filesrecibe una subida multipart con el campofiley devuelve unfile_idválido durante 24 horas.GET /v1/requests/:iddevuelve un resultado anterior. Añade?format=con cualquier formato de salida para obtenerlo en otro.GET /v1/creditsdevuelve tu saldo y el consumo de esta clave.POST /v1/keys/temporarydevuelve una clave temporal con 50 créditos. Sin registro, una al día.
Formatos de salida
markdown
El documento completo en Markdown. Las tablas usan el formato GitHub Flavored Markdown, las fórmulas van entre $...$ y las páginas se separan con <!-- page:N -->.
json
La misma estructura para todos los modelos: páginas, cada una con bloques tipados. Los tipos de bloque son heading, paragraph, list, table, formula, image, header y footer. bbox, confidence y el tamaño de página son null cuando el modelo no los proporciona, como ocurre con los modelos disponibles hoy.
{"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
La respuesta en Markdown más un objeto output con el archivo: format, filename, mime_type, encoding y data. text, html y csv son cadenas UTF-8 (encoding: "utf8"); docx y xlsx van en base64 (encoding: "base64"). csv y xlsx contienen las tablas (una hoja por tabla) o las líneas de texto si no hay tablas. Se acepta txt como alias 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}}Enrutamiento y alternativas
Configura model como auto y elegiremos un modelo para cada documento. Usa route para definir la prioridad: cheapest, fastest o quality.
Añade fallbacks para evitar caídas de servicio. Si el primer modelo da error o supera los límites de peticiones, se ejecuta el siguiente. La respuesta indica qué modelo respondió y solo pagas por ese.
{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}Créditos
Cada modelo tiene un precio en créditos por página. $1 compra 1,000 créditos y no caducan. Todas las respuestas incluyen usage.credits.
- Los resultados fallidos o vacíos son gratuitos.
- Reenviar el mismo archivo al mismo modelo se responde desde la caché de forma gratuita.
- Cada clave de API puede tener su propio límite de créditos.
Errores
Agentes, MCP y CLI
Los agentes de código pueden usar OCRRouter sin necesidad de registrarse. La CLI y el servidor MCP solicitan una clave temporal con 50 créditos en el primer uso y la guardan en ~/.ocrrouter/config.json. Define OCRROUTER_API_KEY para usar tu propia clave.
# CLI
npx ocrrouter invoice.pdf --format markdown
# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcpHay un resumen legible por máquinas de esta página en /llms.txt.