OCRRouter

مستندات API

راهنمای مفاهیم اصلی. تمام اندپوینت‌ها و پارامترها در مرجع API آمده است.

شروع سریع

یک کلید 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.

modelstringشناسه مدل مانند mistral/mistral-ocr یا auto.
file_urlstringآدرس اینترنتی عمومی PDF یا تصویر. از یکی از موارد file_url، file_base64 یا file_id استفاده کنید.
file_base64stringفایل به‌صورت base64، تا ۲۰ مگابایت.
file_idstringشناسه برگردانده‌شده از POST /v1/files برای فایل‌های بزرگ‌تر.
formatstringmarkdown (پیش‌فرض)، json، text، html، csv، docx یا xlsx.
pagesstringمحدوده صفحات، مثلاً 1-5,8. پیش‌فرض همه صفحات است.
fallbacksstring[]شناسه مدل‌ها برای امتحان به ترتیب، در صورتی که مدل اول شکست بخورد.
routestringدر حالت مدل auto: حالت‌های quality (پیش‌فرض)، cheapest یا fastest.
filenamestringنام اختیاری که در گزارش فعالیت‌های شما نمایش داده می‌شود.

سایر اندپوینت‌ها:

  • 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 هستند، که در مدل‌های فعال فعلی به همین صورت است.

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 شامل فایل: format، filename، mime_type، encoding و data. فرمت‌های text، html و csv رشته‌های UTF-8 هستند (encoding: "utf8")؛ docx و xlsx به‌صورت base64 هستند (encoding: "base64"). خروجی‌های csv و xlsx شامل جداول هستند (یک شیت برای هر جدول)، یا خطوط متنی در صورتی که جدولی نباشد. txt نیز به‌عنوان نام دیگری برای 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}}

مسیریابی و جایگزین‌ها

پارامتر 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 می‌تواند سقف اعتبار اختصاصی خود را داشته باشد.

خطاها

400درخواست نامعتبر است یا نوع فایل پشتیبانی نمی‌شود.
401کلید API ارائه نشده یا باطل شده است.
402اعتبار کافی نیست، یا کلید به سقف مصرف خود رسیده است.
413حجم فایل بیشتر از محدودیت مجاز برای این مدل است.
429تعداد درخواست‌ها بیش از حد مجاز است. پس از زمان مشخص‌شده در هدر Retry-After دوباره تلاش کنید.
502تمام مدل‌های موجود در زنجیره جایگزین با خطا مواجه شدند. هزینه‌ای از شما کسر نشد.
503مدل درخواستی شما هنوز متصل نشده است.

ایجنت‌ها، 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 قرار دارد.

سوالات متداول