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رابط URL عام لملف PDF أو صورة. استخدم إما file_url أو file_base64 أو file_id.
file_base64stringالملف بترميز base64، حتى 20 ميجابايت.
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 يستقبل رفع ملف متعدد الأجزاء (multipart) في حقل file، ويعيد file_id صالح لمدة 24 ساعة.
  • GET /v1/requests/:id يسترجع نتيجة سابقة. أضف ?format= مع أي تنسيق مخرجات للحصول عليها بتنسيق آخر.
  • GET /v1/credits يعرض رصيدك واستهلاك هذا المفتاح.
  • POST /v1/keys/temporary يعيد مفتاحاً مؤقتاً برصيد 50. دون تسجيل، مفتاح واحد يومياً.

تنسيقات الإخراج

markdown

المستند بالكامل بتنسيق Markdown. الجداول بتنسيق GitHub، والصيغ الرياضية محاطة بـ $...$، والصفحات مفصولة بـ <!-- 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.

  • النتائج الفاشلة والفارغة مجانية تماماً.
  • إعادة إرسال نفس الملف إلى نفس النموذج تُجلب من التخزين المؤقت (Cache) مجاناً.
  • يمكن تخصيص حد أقصى للرصيد لكل مفتاح API مستقل.

الأخطاء

400الطلب غير صالح أو نوع الملف غير مدعوم.
401مفتاح API مفقود أو تم إبطاله.
402الرصيد غير كافٍ، أو وصل المفتاح إلى الحد الأقصى المسموح به.
413حجم الملف أكبر من الحد المسموح به لهذا النموذج.
429طلبات كثيرة جداً (تجاوز الحد). أعد المحاولة بعد الوقت المحدد في ترويسة Retry-After.
502فشلت جميع النماذج المحددة في قائمة البدائل (fallbacks). لم يتم خصم أي رصيد.
503النموذج المطلوب غير متصل بالخدمة بعد.

الوكلاء، وMCP، وواجهة سطر الأوامر (CLI)

يمكن لوكلاء البرمجة استخدام OCRRouter دون الحاجة لخطوة تسجيل. تطلب واجهة سطر الأوامر وخادم 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.

الأسئلة الشائعة