OCRRouter

Documentación de la API

Guías sobre los conceptos principales. Todos los endpoints y parámetros están en la referencia de la API.

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.

modelstringEl ID de un modelo como mistral/mistral-ocr, o auto.
file_urlstringURL pública de un PDF o imagen. Usa file_url, file_base64 o file_id.
file_base64stringEl archivo en base64, hasta 20 MB.
file_idstringID devuelto por POST /v1/files, para archivos más grandes.
formatstringmarkdown (predeterminado), json, text, html, csv, docx o xlsx.
pagesstringRango de páginas, por ejemplo 1-5,8. Por defecto incluye todas.
fallbacksstring[]IDs de modelos a probar, en orden, si el primero falla.
routestringCon el modelo auto: quality (predeterminado), cheapest o fastest.
filenamestringNombre opcional que se muestra en tu historial de actividad.

Otros endpoints:

  • GET /v1/models lista todos los modelos, su precio y disponibilidad. No requiere clave.
  • POST /v1/files recibe una subida multipart con el campo file y devuelve un file_id válido durante 24 horas.
  • GET /v1/requests/:id devuelve un resultado anterior. Añade ?format= con cualquier formato de salida para obtenerlo en otro.
  • GET /v1/credits devuelve tu saldo y el consumo de esta clave.
  • POST /v1/keys/temporary devuelve 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.

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

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.

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}}

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

400La solicitud es incorrecta o el tipo de archivo no es compatible.
401Falta la clave de API o ha sido revocada.
402Créditos insuficientes, o la clave alcanzó su límite de créditos.
413El archivo supera el tamaño máximo permitido para este modelo.
429Demasiadas solicitudes. Vuelve a intentarlo después del tiempo indicado en el encabezado Retry-After.
502Todos los modelos de la cadena de alternativas fallaron. No se te cobra nada.
503El modelo solicitado aún no está disponible.

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 mcp

Hay un resumen legible por máquinas de esta página en /llms.txt.

Preguntas frecuentes