شروع سریع
یک کلید API بسازید، سپس یک فایل ارسال کنید. حسابهای جدید با 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"
}'درخواست
POST https://api.ocrrouter.ai/v1/ocr همراه با بدنه JSON و هدر Authorization: Bearer.
| model | string | شناسه مدل مانند mistral/mistral-ocr یا auto. |
| file_url | string | آدرس اینترنتی عمومی PDF یا تصویر. از یکی از موارد file_url، file_base64 یا file_id استفاده کنید. |
| file_base64 | string | فایل بهصورت base64، تا ۲۰ مگابایت. |
| file_id | string | شناسه برگرداندهشده از POST /v1/files برای فایلهای بزرگتر. |
| format | string | markdown (پیشفرض)، json، text، html، csv، docx یا xlsx. |
| pages | string | محدوده صفحات، مثلاً 1-5,8. پیشفرض همه صفحات است. |
| fallbacks | string[] | شناسه مدلها برای امتحان به ترتیب، در صورتی که مدل اول شکست بخورد. |
| route | string | در حالت مدل auto: حالتهای quality (پیشفرض)، cheapest یا fastest. |
| filename | string | نام اختیاری که در گزارش فعالیتهای شما نمایش داده میشود. |
سایر اندپوینتها:
GET /v1/modelsفهرست تمام مدلها، قیمت و وضعیت دردسترس بودن آنها را برمیگرداند. نیازی به کلید نیست.POST /v1/filesیک آپلود چندبخشی با فیلدfileدریافت کرده و یکfile_idبرمیگرداند که تا ۲۴ ساعت معتبر است.GET /v1/requests/:idنتیجه قبلی را برمیگرداند. برای دریافت با فرمتی دیگر،?format=را همراه با فرمت خروجی دلخواه اضافه کنید.GET /v1/creditsموجودی شما و میزان مصرف این کلید را برمیگرداند.POST /v1/keys/temporaryیک کلید موقت با 50 اعتبار برمیگرداند. بدون ثبتنام، روزی یک بار.
فرمتهای خروجی
markdown
کل سند بهصورت Markdown. جدولها با فرمت GitHub-flavoured هستند، فرمولها داخل $...$ قرار دارند و صفحات با <!-- page:N --> از هم جدا شدهاند.
json
ساختار یکسان از هر مدل: صفحات، هر کدام شامل بلوکهای تایپشده. انواع بلوک عبارتند از: heading، paragraph، list، table، formula، image، header و footer. مقادیر bbox، confidence و اندازه صفحه در صورتی که مدل آنها را ارائه ندهد null هستند، که در مدلهای فعال فعلی به همین صورت است.
{"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 شامل فایل: format، filename، mime_type، encoding و data. فرمتهای text، html و csv رشتههای UTF-8 هستند (encoding: "utf8")؛ docx و xlsx بهصورت base64 هستند (encoding: "base64"). خروجیهای csv و xlsx شامل جداول هستند (یک شیت برای هر جدول)، یا خطوط متنی در صورتی که جدولی نباشد. txt نیز بهعنوان نام دیگری برای 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}}مسیریابی و جایگزینها
پارامتر model را روی auto بگذارید تا ما برای هر سند مدلی را انتخاب کنیم. از route برای مشخص کردن اولویت استفاده کنید: cheapest، fastest یا quality.
برای حفظ پایداری سرویس هنگام اختلالات، مدلهای جایگزین (fallbacks) را اضافه کنید. اگر مدل اول با خطا مواجه شود یا با محدودیت نرخ روبرو گردد، مدل بعدی اجرا میشود. پاسخ به شما میگوید کدام مدل پاسخ داده است، و شما فقط هزینه همان مدل را میپردازید.
{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}اعتبارها
هر مدل قیمتی بر حسب اعتبار به ازای هر صفحه دارد. با ۱ دلار 1,000 اعتبار خریداری میشود و اعتبارها منقضی نمیشوند. هر پاسخ شامل usage.credits است.
- نتایج ناموفق و خالی رایگان هستند.
- ارسال مجدد همان فایل به همان مدل، بهصورت رایگان از حافظه پنهان (کش) پاسخ داده میشود.
- هر کلید API میتواند سقف اعتبار اختصاصی خود را داشته باشد.
خطاها
ایجنتها، MCP و CLI
ایجنتهای برنامهنویسی میتوانند بدون نیاز به مرحله ثبتنام از OCRRouter استفاده کنند. ابزار CLI و سرور MCP در اولین استفاده یک کلید موقت با 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خلاصه ماشینخوان این صفحه در /llms.txt قرار دارد.