OCRRouter

תיעוד ה-API

מדריכים לעקרונות המרכזיים. כל נקודת קצה (endpoint) ופרמטר מפורטים ב-API reference.

התחלה מהירה

יוצרים מפתח 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 MB.
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

אותו מבנה מכל מודל: עמודים, שבכל אחד מהם בלוקים עם טיפוסים (types). טיפוסי הבלוקים הם 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}}

ניתוב וגיבויים (fallbacks)

הגדירו את 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 קונה 1,000 קרדיטים והם אינם פגים לעולם. כל תשובה כוללת את usage.credits.

  • תוצאות שנכשלו או ריקות הן בחינם.
  • שליחה חוזרת של אותו קובץ לאותו מודל מוגשת מהמטמון (cache) בחינם.
  • לכל מפתח API יכולה להיות מגבלת קרדיטים משלו.

שגיאות

400הבקשה אינה תקינה או שסוג הקובץ אינו נתמך.
401מפתח ה-API חסר או בוטל.
402אין מספיק קרדיטים, או שהמפתח הגיע למגבלת הקרדיטים שלו.
413הקובץ גדול מהמגבלה של מודל זה.
429יותר מדי בקשות. נסו שוב לאחר הזמן המצוין בכותרת Retry-After.
502כל המודלים בשרשרת הגיבוי (fallback) נכשלו. לא תחויבו.
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.

שאלות נפוצות