# OCR

> حوّل ملفات PDF والمستندات الممسوحة والصور إلى نص وMarkdown وجداول مع Tarout OCR

# Tarout OCR

يقرأ Tarout OCR ملفات PDF والصفحات الممسوحة وصور الجوال، ويعيد لكل صفحة نصًا
بصيغة Markdown ونصًا عاديًا وجداول. صُمم للعربية والإنجليزية، بما في ذلك
الصفحات المختلطة والتشكيل والخط اليدوي والجداول والنماذج.

وهو جزء من AI Gateway: مفاتيح `sk_tarout_...` نفسها، والرصيد المسبق نفسه،
والعنوان الأساسي نفسه.

## اختر المنطقة

تختار مكان قراءة صفحاتك بحقل واحد هو `model`. يبقى باقي الطلب كما هو.

| المنطقة | مكان قراءة الصفحات | `model` في API | سطر الأوامر | `ocr_process` في MCP |
| --- | --- | --- | --- | --- |
| **محلي** (الافتراضي) | داخل السعودية. لا تغادر الصفحات المملكة. | `"tarout-ocr"` | `--region local` | `"region": "local"` |
| **عالمي** | خارج السعودية، لدى مزوّد لا يحتفظ بأي نسخة من بياناتك. | `"tarout-ocr-global"` | `--region global` | `"region": "global"` |

إذا لم ترسل `model` يُستخدم المحلي. تذكر الاستجابة قيمة `model` التي قرأت
مستندك. في استوديو OCR اختر المنطقة من **المنطقة**، فيتغير الكود أسفلها
ليطابقها. يتطلب الخيار `--region` الإصدار 1.16.0 أو أحدث من Tarout CLI.

تُعالَج المستندات في الذاكرة، ولا تُخزَّن بعد الاستجابة.

```
POST https://tarout.sa/api/ai/v1/ocr
```

## التسعير

تُخصم التكلفة من الرصيد المسبق لمنظمتك، وفقط للصفحات التي تُقرأ بنجاح. الصفحة
التي تفشل لا تُحتسب.

يُحتسب OCR حسب الاستخدام في `tarout-ocr` و`tarout-ocr-global`. يعتمد سعر الصفحة
على حجمها وعلى كمية النص فيها.
 كل استجابة تذكر تكلفتها في `usage_info.billed_halalas`
(100 هللة = 1 ريال). تكلفة الصفحة غالبًا أقل من هللة واحدة، لذلك قد تكون
القيمة كسرًا. يُخصم من محفظتك بالهللات الكاملة: تتجمع الكسور وتُخصم عندما
تبلغ هللة واحدة.

يجب أن يملك مفتاحك صلاحية **OCR**. أنشئ المفاتيح أو عدّلها من **الإعدادات، مفاتيح API**.

## البداية السريعة

تقرأ الأمثلة فاتورة نموذجية عامة بالعربية والإنجليزية. ضع رابط مستندك بدلًا منها.

```sh
curl https://tarout.sa/api/ai/v1/ocr \
  -H "Authorization: Bearer $TAROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tarout-ocr",
    "document": { "type": "document_url", "document_url": "https://tarout.sa/samples/ocr-invoice.pdf" }
  }'
```

للقراءة في المنطقة العالمية غيّر سطرًا واحدًا: `"model": "tarout-ocr-global"`.

من JavaScript أو Python:

```js
// Node.js 18+ (save as ocr.mjs). Reads TAROUT_API_KEY.
const res = await fetch("https://tarout.sa/api/ai/v1/ocr", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TAROUT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tarout-ocr",
    document: { type: "document_url", document_url: "https://tarout.sa/samples/ocr-invoice.pdf" },
  }),
});
const result = await res.json();
if (!res.ok) throw new Error(result.error.message);

for (const page of result.pages) {
  console.log(page.status === "ok" ? page.markdown : `Page ${page.index} failed: ${page.error.message}`);
}
```

```python
import os, requests  # pip install requests

res = requests.post(
    "https://tarout.sa/api/ai/v1/ocr",
    headers={"Authorization": f"Bearer {os.environ['TAROUT_API_KEY']}"},
    json={
        "model": "tarout-ocr",
        "document": {"type": "document_url", "document_url": "https://tarout.sa/samples/ocr-invoice.pdf"},
    },
)
result = res.json()
if not res.ok:
    raise RuntimeError(result["error"]["message"])

for page in result["pages"]:
    print(page["markdown"] if page["status"] == "ok" else f"Page {page['index']} failed: {page['error']['message']}")
```

من سطر الأوامر، بملف محلي أو رابط:

```sh
tarout ai ocr ./contract.pdf --format md --out contract.md
tarout ai ocr https://tarout.sa/samples/ocr-invoice.pdf --format json
tarout ai ocr ./scan.jpg --region global --format txt
```

ويحصل الوكلاء المتصلون عبر MCP على أداة `ocr_process`.

## الطلب

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `model` | نص | `tarout-ocr` (الافتراضي، محلي) أو `tarout-ocr-global` (عالمي). راجع [اختر المنطقة](#اختر-المنطقة). |
| `document` | كائن | `{ "type": "document_url", "document_url": "..." }` أو `{ "type": "image_url", "image_url": "..." }`. يقبل كل منهما رابطًا عامًا أو data URL بترميز base64 مثل `data:application/pdf;base64,...`. |
| `pages` | مصفوفة أرقام | اختياري. أرقام الصفحات المطلوبة تبدأ من 0. عند حذفه تُقرأ كل الصفحات. |
| `normalize` | كائن | اختياري. `{ "digits": "latin" }` يحوّل الأرقام الهندية إلى 0-9. افتراضيًا تبقى كل الأرقام كما طُبعت. |
| `stream` | قيمة منطقية | اختياري. `true` يرسل كل صفحة فور جاهزيتها (انظر أدناه). |

الملفات المدعومة: PDF وPNG وJPEG وWebP وTIFF وGIF وAVIF، حتى 10 ميجابايت و100
صفحة لكل طلب. صور HEIC غير مدعومة: صدّرها بصيغة JPEG. وتُرفض ملفات PDF
المحمية بكلمة مرور.

شكل الطلب متوافق مع Mistral OCR: إن كنت تستخدمه، غيّر العنوان الأساسي والمفتاح
فقط.

## الاستجابة

```json
{
  "id": "ocr_8f2c...",
  "object": "ocr.document",
  "model": "tarout-ocr",
  "pages": [
    {
      "index": 0,
      "status": "ok",
      "markdown": "# فاتورة ضريبية\n\n| الصنف | الكمية | السعر |\n| --- | --- | --- |\n| قهوة | 2 | 15.00 |",
      "text": "فاتورة ضريبية\n\nالصنف\tالكمية\tالسعر\nقهوة\t2\t15.00",
      "tables": [{ "format": "markdown", "rows": [["الصنف", "الكمية", "السعر"], ["قهوة", "2", "15.00"]] }],
      "dimensions": { "width": 1131, "height": 1600 },
      "truncated": false
    }
  ],
  "usage_info": { "pages_processed": 1, "pages_failed": 0, "doc_size_bytes": 182311, "billed_halalas": 0.39 },
  "latency_ms": 2140
}
```

- يحافظ `markdown` على العناوين والقوائم والجداول. الجداول ذات الخلايا المدمجة
  تأتي ككتل HTML `<table>` داخل Markdown.
- `text` هو المحتوى نفسه كنص عادي، وخلايا الجداول مفصولة بعلامة Tab.
- `tables` يسرد كل جداول الصفحة كصفوف من الخلايا.
- الصفحة التي تعذّرت قراءتها تحمل `"status": "failed"` وحقل `error`، وتعود
  بقية الصفحات كالمعتاد، ولا تُحتسب إلا الصفحات الناجحة.
- `truncated: true` يعني أن الصفحة بلغت حد المخرجات وقد ينقص آخرها.

## البث المباشر

مع `"stream": true` تأتي الاستجابة بصيغة Server-Sent Events. تصل الصفحات بترتيب
انتهائها، وكل منها يحمل `index`:

```
data: {"type":"start","id":"ocr_8f2c...","pages":[0,1,2]}
data: {"type":"page","id":"ocr_8f2c...","page":{"index":1,"status":"ok","markdown":"..."}}
data: {"type":"page","id":"ocr_8f2c...","page":{"index":0,"status":"ok","markdown":"..."}}
data: {"type":"done","id":"ocr_8f2c...","usage_info":{...},"latency_ms":3120}
data: [DONE]
```

إذا أغلقت الاتصال مبكرًا تتوقف الصفحات المتبقية، ولا تُحتسب إلا الصفحات التي
وصلتك.

## الأخطاء

تستخدم الأخطاء صيغة AI Gateway: `{ "error": { "message", "type", "code" } }`.

| الحالة | المعنى |
| --- | --- |
| 400 | الطلب غير صالح، أو صفحة في `pages` غير موجودة. |
| 401 | المفتاح مفقود أو غير صالح. |
| 403 | المفتاح لا يملك صلاحية OCR. أضفها من الإعدادات، مفاتيح API. |
| 402 | الرصيد المسبق غير كافٍ. اشحنه من لوحة التحكم. |
| 413 | حجم المستند أكبر من 10 ميجابايت أو يطلب أكثر من 100 صفحة. |
| 415 | نوع الملف غير مدعوم. |
| 422 | ملف PDF تالف أو محمي بكلمة مرور. |
| 429 | حد الطلبات: 60 طلبًا و120 صفحة في الدقيقة لكل مفتاح. |
| 503 | OCR مشغول أو غير متاح مؤقتًا (`OCR_BUSY` أو `OCR_UNAVAILABLE`). أعد المحاولة بعد قليل؛ الصفحات المرفوضة لانشغال الخدمة لا تُحتسب. |

## استوديو OCR

جرّب OCR دون كتابة كود من لوحة التحكم: **الذكاء الاصطناعي، استوديو OCR**. أفلت ملفًا،
وشاهد كل صفحة تظهر بجانب الأصل، ونزّل النتيجة بصيغة Markdown أو نص أو JSON.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md