صورة إلى نص

POST /api/v1/image-to-text

الطلب

أرسل صورة واحدة بحقل multipart المسمى image باستخدام POST، واستبدل YOUR_API_KEY وdocument.png. دع cURL يحدد حدود multipart. لا يُسمح إلا بمعامل format الاختياري، دون حقول أو إعدادات نموذج إضافية. راجع مصادقة Bearer وحماية المفتاح.

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

استجابة JSON أدناه توضيحية؛ يختلف النص وعدد الرموز بحسب الصورة. راجع قواعد منع التكرار قبل إعادة المحاولة.

استجابة ناجحة (مثال استخدام)

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "text": "# Document title\n\nRecognized paragraph.\n\n| Item | Count |\n| --- | --- |\n| Books | 12 |",
  "usage": {
    "input_tokens": 2000,
    "output_tokens": 4000
  },
  "billing": {
    "currency": "USD",
    "price_version": "2026-10-26-v1",
    "base_usd": "0.002000000",
    "input_overage_usd": "0.000000000",
    "output_overage_usd": "0.002400000",
    "total_usd": "0.004400000"
  }
}

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

يُقبل معامل اختياري واحد فقط: format=json|text|docx. تعيد المعاملات المجهولة أو المكررة أو غير الصحيحة 400 قبل التعرف. يعيد json افتراضياً Markdown داخل text، وقد يتضمن جداول HTML وصيغ LaTeX. يحوّل text هذا الحقل فقط إلى نص عادي مع إبقاء usage وbilling. يعيد docx مرفق Word باسم result.docx.

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

curl --silent --show-error --fail --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=docx' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png' \
  --dump-header - --output result.docx

يستخدم Word الترويسات Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document وContent-Disposition: attachment. لا تستخدم الملف إلا عند نجاح cURL ومطابقة Content-Type. تصف X-Request-Id وX-OCR-Charged-USD وX-OCR-Price-Version عملية التعرف الأصلية. تبقى Cache-Control: no-store وIdempotency-Replayed عند انطباقها.

خلال 24 ساعة يمكن تغيير التنسيق بالحساب نفسه وبايتات الصورة وMIME وIdempotency-Key نفسها دون رسوم تعرف جديدة. بعد انتهاء المدة قد تبدأ عملية جديدة مدفوعة. تحويل النص القديم لا يستعيد البنية المفقودة.

يعني export_failed ‏(503) أن التعرف نجح وخُصمت رسومه، لكن التحويل فشل؛ تكون recognition_succeeded بقيمة true في خطأ JSON. أعد المحاولة بالصورة والمفتاح الأصليين قبل انتهاء الصلاحية، أو اطلب format=json. لا تُرد الرسوم ولا يتكرر التعرف. يحفظ Word نصوصاً وجداول قابلة للتحرير دون مطابقة التخطيط الأصلي، وتبقى الصيغ نص LaTeX.

تتطلب كل عملية أو نقطة وصول جديدة Idempotency-Key جديداً؛ تؤدي مشاركته بين واجهتي النص والجداول إلى 409 idempotency_conflict. عند تغيير التنسيق للعملية نفسها احتفظ بالمفتاح والصورة الأصليين. راجع منع التكرار والتسعير.