OCRRouter

API ලියකියවිලි (Documentation)

ප්‍රධාන සංකල්ප සඳහා මාර්ගෝපදේශ. සෑම endpoint සහ parameter එකක්ම API reference හි ඇත.

Quickstart

API යතුරක් සාදාගෙන, ගොනුවක් යවන්න. නව ගිණුම් නොමිලේ ලැබෙන credits 50 කින් ආරම්භ වේ.

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

Request එක

JSON body එකක් සහ Authorization: Bearer header එකක් සහිතව POST https://api.ocrrouter.ai/v1/ocr කරන්න.

modelstringmistral/mistral-ocr වැනි model ID එකක්, හෝ auto.
file_urlstringPDF එකක හෝ පින්තූරයක ප්‍රසිද්ධ (public) URL එකක්. file_url, file_base64 හෝ file_id අතුරින් එකක් භාවිතා කරන්න.
file_base64stringගොනුව base64 ලෙස, 20 MB දක්වා.
file_idstringවිශාල ගොනු සඳහා POST /v1/files මඟින් ලබා දුන් ID එක.
formatstringmarkdown (පෙරනිමි), json, text, html, csv, docx හෝ xlsx.
pagesstringපිටු පරාසය, උදාහරණයක් ලෙස 1-5,8. පෙරනිමියෙන් සියලුම පිටු.
fallbacksstring[]පළමු model එක අසාර්ථක වුවහොත්, අනුපිළිවෙලින් උත්සාහ කළ යුතු Model IDs.
routestringmodel එක auto වූ විට: quality (පෙරනිමි), cheapest හෝ fastest.
filenamestringඔබගේ activity log හි පෙන්වන විකල්ප නම.

වෙනත් endpoints:

  • GET /v1/models මඟින් සෑම model එකක්ම, එහි මිල සහ එය ලබාගත හැකිද යන්න පෙන්වයි. API යතුරක් අවශ්‍ය නොවේ.
  • POST /v1/files මඟින් file field එකක් සමඟ multipart upload එකක් භාරගෙන පැය 24ක් වලංගු file_id එකක් ලබා දෙයි.
  • GET /v1/requests/:id මඟින් පෙර ප්‍රතිඵලයක් ලබා දෙයි. එය වෙනත් ආකෘතියකින් ලබා ගැනීමට ඕනෑම output format එකක් සමඟ ?format= එක් කරන්න.
  • GET /v1/credits මඟින් ඔබගේ ශේෂය (balance) සහ මෙම යතුරේ භාවිතය පෙන්වයි.
  • POST /v1/keys/temporary මඟින් credits 50 සහිත තාවකාලික යතුරක් ලබා දෙයි. ලියාපදිංචි වීමක් අවශ්‍ය නැත, දිනකට එකකි.

ප්‍රතිදාන ආකෘති (Output formats)

markdown

සම්පූර්ණ ලේඛනය Markdown ලෙස. වගු GitHub-flavoured tables වන අතර, සූත්‍ර $...$ මඟින් දක්වා ඇත, පිටු <!-- page:N --> මඟින් වෙන් කර ඇත.

json

සෑම model එකකින්ම එකම ව්‍යුහය: පිටු, ඒ සෑම එකක්ම typed blocks සහිතයි. Block වර්ග වන්නේ heading, paragraph, list, table, formula, image, header සහ footer වේ. Model එක මඟින් ලබා නොදෙන විට bbox, confidence සහ පිටු ප්‍රමාණය null වේ (දැනට සක්‍රීය model වල තත්වය මෙයයි).

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

Markdown ප්‍රතිචාරය සමඟ ගොනුවක් අඩංගු output object එකක්: format, filename, mime_type, encoding සහ data. text, html සහ csv යනු UTF-8 strings වේ (encoding: "utf8"); docx සහ xlsx යනු base64 වේ (encoding: "base64"). csv සහ xlsx හි වගු (එක් වගුවකට එක් sheet එකක් බැගින්), හෝ වගු නොමැති විට පෙළ පේළි අඩංගු වේ. text සඳහා තවත් නමක් ලෙස txt ද පිළිගනු ලැබේ.

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

Routing සහ fallbacks

model එක auto ලෙස සකසන්න, එවිට අපි එක් එක් ලේඛනය සඳහා සුදුසු model එකක් තෝරා ගනිමු. වැදගත් වන්නේ කුමක්දැයි සඳහන් කිරීමට route භාවිතා කරන්න: cheapest, fastest හෝ quality.

බිඳවැටීම් වලදීද අඛණ්ඩව ක්‍රියාත්මක වීමට fallbacks එක් කරන්න. පළමු model එකේ දෝෂයක් හෝ rate-limit එකක් ඇති වුවහොත්, ඊළඟ එක ක්‍රියාත්මක වේ. කුමන model එකෙන් පිළිතුරු ලැබුණිදැයි ප්‍රතිචාරයෙන් කියැවෙන අතර, ඔබ ගෙවිය යුත්තේ ඒ සඳහා පමණි.

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

Credits

සෑම model එකකටම පිටුවකට credits වලින් මිලක් ඇත. $1 කට credits 1,000 ක් ලැබෙන අතර ඒවා කල් ඉකුත් නොවේ. සෑම ප්‍රතිචාරයකම usage.credits ඇතුළත් වේ.

  • අසාර්ථක සහ හිස් ප්‍රතිඵල නොමිලේ.
  • එම ගොනුවම නැවත එම model එකටම යැවීම cache එකෙන් නොමිලේ ලබා දේ.
  • සෑම API යතුරකටම ඊටම ආවේණික credit සීමාවක් තිබිය හැක.

දෝෂ (Errors)

400Request එක දෝෂ සහිතයි හෝ ගොනු වර්ගය සඳහා සහාය නොදක්වයි.
401API යතුර අස්ථානගත වී ඇත හෝ අවලංගු කර ඇත.
402ප්‍රමාණවත් credits නැත, නැතහොත් යතුර එහි credit සීමාවට ළඟා වී ඇත.
413මෙම model එක සඳහා වන සීමාවට වඩා ගොනුව විශාලය.
429ඉල්ලීම් (requests) ප්‍රමාණය වැඩියි. Retry-After header හි ඇති කාලයෙන් පසු නැවත උත්සාහ කරන්න.
502Fallback දාමයේ ඇති සියලුම model අසාර්ථක විය. ඔබෙන් මුදල් අය නොකෙරේ.
503ඔබ ඉල්ලා සිටි model එක තවමත් සම්බන්ධ කර නොමැත.

Agents, MCP සහ CLI

Coding agents වලට ලියාපදිංචි වීමකින් තොරව OCRRouter භාවිතා කළ හැක. CLI සහ MCP server මඟින් පළමු භාවිතයේදී credits 50 සහිත තාවකාලික යතුරක් ඉල්ලා සිටින අතර එය ~/.ocrrouter/config.json හි සුරකියි. ඔබගේම යතුරක් භාවිතා කිරීමට OCRROUTER_API_KEY සකසන්න.

# CLI
npx ocrrouter invoice.pdf --format markdown

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

මෙම පිටුවේ machine-readable සාරාංශයක් /llms.txt හි ඇත.

ප්‍රශ්න