صورة إلى جدول

POST /api/v1/image-to-table

ارفع صورة واحدة في حقل multipart image إلى POST /api/v1/image-to-table؛ الصيغ المتاحة هي json (افتراضياً) وcsv وxlsx فقط. استبدل YOUR_API_KEY وtable.png ونفّذ الطلب من الخادم حسب مصادقة Bearer.

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

يتضمن رد JSON الناجح request_id وusage وbilling ومصفوفة tables من العناصر {title, html}. يُنقّى HTML للحماية، وTable N اسم بديل لا يعني أن الصورة احتوت على ذلك العنوان. لا نُرجع النص الخام للنموذج.

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "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"
  },
  "tables": [
    {
      "title": "Sales",
      "html": "<table><tbody><tr><th>Item</th><th>Qty</th></tr><tr><td>Notebook</td><td>0012</td></tr></tbody></table>"
    }
  ]
}

يمكنك استخدام الصورة نفسها وIdempotency-Key نفسه للحصول على الصيغ الأخرى دون إعادة التعرف أو احتساب رسوم جديدة:

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

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

• CSV: جدول واحد يعني ملف UTF-8 CSV عادياً. عند وجود جداول متعددة تفصل بينها أسطر فارغة ويبدأ كل قسم بـ# Table N: Title. هذا ليس ملف CSV قياسياً لجدول واحد؛ افصل الأقسام قبل الاستيراد. تُعطّل القيم الشبيهة بالصيغ البرمجية
• XLSX: مصنف Excel يحتوي على ورقة Table N لكل جدول، مع الحفاظ على الخلايا المدمجة. تُحفظ جميع الأرقام والأصفار البادئة كنصوص؛ راجعها قبل الحساب
• المدخلات: لا تقبل API إلا صورة واحدة PNG أو JPEG أو WebP حتى 10 ميغابايت. تدعم أداة الويب أيضاً HEIC وHEIF وBMP، لكن API لا تدعمها. لا تدعم PDF أو الملفات متعددة الصفحات أو الرفع المجمع؛ يمكن للصورة الواحدة احتواء عدة جداول

أخطاء الجداول والقواعد المشتركة

إذا لم يُكتشف جدول صالح، يعود 422 no_tables قبل التسوية دون رسوم مع تحرير الحجز. إذا فشل إخراج CSV/XLSX بعد نجاح التعرف والتسوية، يعود 503 export_failed مع recognition_succeeded: true. أعد طلب format=json خلال فترة إعادة النتيجة باستخدام الصورة والحساب وIdempotency-Key نفسها؛ لا تبدأ عملية جديدة أثناء عدم وضوح الخصم. الأخطاء JSON تتضمن request_id وerror.code وCache-Control: no-store. تتضمن الملفات الناجحة X-Request-Id وX-OCR-Charged-USD وX-OCR-Price-Version.

تغيير format للعملية نفسها لا يعيد التعرف أو الخصم. تتاح إعادة النتيجة خلال 24 ساعة وتُحتسب ضمن حدود الطلبات. مشاركة المفتاح بين الواجهتين تؤدي إلى 409 idempotency_conflict، ورصيد API منفصل عن رصيد الموقع. راجع الأسعار والحجز وحدود الطلبات ومنع التكرار وإعادة المحاولة.