البدء السريع
أنشئ مفتاح 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 | رابط URL عام لملف PDF أو صورة. استخدم إما file_url أو file_base64 أو file_id. |
| file_base64 | string | الملف بترميز base64، حتى 20 ميجابايت. |
| 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يستقبل رفع ملف متعدد الأجزاء (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 عندما لا يوفرها النموذج، وهو الحال مع النماذج المتاحة حالياً.
{"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.
- النتائج الفاشلة والفارغة مجانية تماماً.
- إعادة إرسال نفس الملف إلى نفس النموذج تُجلب من التخزين المؤقت (Cache) مجاناً.
- يمكن تخصيص حد أقصى للرصيد لكل مفتاح API مستقل.
الأخطاء
الوكلاء، و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.