OCRRouter

Documentation de l'API

Guides des concepts clés. Retrouvez chaque endpoint et paramètre dans la référence de l'API.

Démarrage rapide

Créez une clé API, puis envoyez un fichier. Les nouveaux comptes démarrent avec 50 crédits gratuits.

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

Requête

POST https://api.ocrrouter.ai/v1/ocr avec un corps JSON et un en-tête Authorization: Bearer.

modelstringUn identifiant de modèle tel que mistral/mistral-ocr, ou auto.
file_urlstringURL publique d'un PDF ou d'une image. Utilisez file_url, file_base64 ou file_id.
file_base64stringLe fichier en base64, jusqu'à 20 Mo.
file_idstringIdentifiant renvoyé par POST /v1/files, pour les fichiers plus volumineux.
formatstringmarkdown (par défaut), json, text, html, csv, docx ou xlsx.
pagesstringPlage de pages, par exemple 1-5,8. Par défaut, toutes les pages.
fallbacksstring[]Identifiants des modèles à tester, dans l'ordre, si le premier échoue.
routestringAvec le modèle auto : quality (par défaut), cheapest ou fastest.
filenamestringNom facultatif affiché dans votre journal d'activité.

Autres endpoints :

  • GET /v1/models liste tous les modèles, leur tarif et leur disponibilité. Aucune clé requise.
  • POST /v1/files accepte un téléversement multipart avec un champ file et renvoie un file_id valable 24 heures.
  • GET /v1/requests/:id renvoie un résultat antérieur. Ajoutez ?format= avec n'importe quel format de sortie pour l'obtenir dans un autre format.
  • GET /v1/credits renvoie votre solde et l'utilisation de cette clé.
  • POST /v1/keys/temporary renvoie une clé temporaire avec 50 crédits. Sans inscription, une par jour.

Formats de sortie

markdown

L'intégralité du document en Markdown. Les tableaux sont au format GitHub Flavored Markdown, les formules sont entourées de $...$, et les pages sont séparées par <!-- page:N -->.

json

La même structure pour chaque modèle : des pages, chacune contenant des blocs typés. Les types de blocs sont heading, paragraph, list, table, formula, image, header et footer. bbox, confidence et les dimensions de page sont null lorsque le modèle ne les fournit pas, ce qui est le cas des modèles actuellement déployés.

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 réponse Markdown complétée par un objet output contenant un fichier : format, filename, mime_type, encoding et data. text, html et csv sont des chaînes UTF-8 (encoding: "utf8") ; docx et xlsx sont en base64 (encoding: "base64"). csv et xlsx contiennent les tableaux (une feuille par tableau), ou les lignes de texte s'il n'y en a aucun. txt est accepté comme synonyme 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}}

Routage et fallbacks

Définissez model sur auto et nous choisissons un modèle pour chaque document. Utilisez route pour définir votre priorité : cheapest, fastest ou quality.

Ajoutez des fallbacks pour continuer à fonctionner en cas de panne. Si le premier modèle renvoie une erreur ou est limité par le débit, le suivant prend le relais. La réponse indique quel modèle a répondu, et vous ne payez que pour celui-ci.

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

Crédits

Chaque modèle a un tarif en crédits par page. 1 $ achète 1,000 crédits et ils n'expirent jamais. Chaque réponse inclut usage.credits.

  • Les requêtes échouées et les résultats vides sont gratuits.
  • Renvoyer le même fichier au même modèle est servi gratuitement depuis le cache.
  • Chaque clé API peut avoir sa propre limite de crédits.

Erreurs

400La requête est mal formée ou le type de fichier n'est pas pris en charge.
401La clé API est manquante ou a été révoquée.
402Crédits insuffisants, ou la clé a atteint sa limite de crédits.
413Le fichier dépasse la limite autorisée pour ce modèle.
429Trop de requêtes. Réessayez après le délai indiqué dans l'en-tête Retry-After.
502Tous les modèles de la chaîne de fallback ont échoué. Vous n'êtes pas facturé.
503Le modèle demandé n'est pas encore connecté.

Agents, MCP et CLI

Les agents de code peuvent utiliser OCRRouter sans étape d'inscription. Le CLI et le serveur MCP demandent une clé temporaire avec 50 crédits dès la première utilisation et l'enregistrent dans ~/.ocrrouter/config.json. Définissez OCRROUTER_API_KEY pour utiliser votre propre clé.

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

Un résumé de cette page lisible par une machine est disponible sur /llms.txt.

Questions fréquentes