الملفات

يقرأ مساران الملفات بمحلّل واحد، وبالخيارات نفسها والنتيجة نفسها:

المسار	الوظيفة	الحجم
`POST /namespaces/:namespace/files`	يخزّن الملف كمستند واحد قابل للبحث؛ ويذكر البحث الصفحة أو الشريحة أو الصفوف التي تجيب	حتى 512 MiB و5,000 صفحة
`POST /parse`	يعيد الملف بصيغة Markdown؛ لا يخزّن شيئًا	حتى 20 MiB

تُقرأ المسوحات الضوئية والصور بتقنية OCR، مهما بلغ عدد الصفحات. الصيغ المدعومة: أنواع الملفات.

رفع ملف

POST /namespaces/:namespace/files أرسل بايتات الملف كجسم الطلب، أو كجزء ملف في نموذج multipart، أو كـ JSON {"url": "https://..."} ليجلبه Conare.

curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});

Response

{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

تنتظر الإجابة حتى wait ثانية لقراءة الملف: 200 عندما يكون ready أو failed، وإلا 202 أثناء قراءته.

الخيارات

معاملات الاستعلام، على المسارين ما لم يُذكر خلاف ذلك.

الخيار	النوع	الوظيفة
`name`	string	اسم الملف، حتى 4,096 حرفًا؛ امتداده يميّز `.csv` و`.tsv` و`.md` عن النص
`id`	string	للرفع فقط. معرّف الملف، وهو نهاية معرّف مستنده؛ القيمة الافتراضية `name` مع استبدال الأحرف الأخرى بـ `-`
`type`	string	`pdf` و`docx` و`pptx` و`xlsx` و`csv` و`png` و… (الكل)؛ وإلا يُستنتج من البايتات، ثم من الاسم
`user`	string	للرفع فقط. مالك الملف؛ حذف المستخدم يحذفه
`metadata`	string	للرفع فقط. كائن JSON يُنسخ إلى البيانات الوصفية للمستند
`pages`	string	الصفحات أو الشرائح أو الإطارات المطلوب قراءتها، مثل `1-20,25` أو `5-`
`password`	string	يفتح ملف PDF أو Word أو PowerPoint أو Excel محميًا، حتى 20 MiB
`layout`	boolean، الافتراضي `false`	يحمل كل جزء مقروء بـ OCR أيضًا `blocks`: مناطق صفحته (الحقول)
`wait`	ثوانٍ، الافتراضي 60	مدة انتظار القراءة قبل `202`، حتى 300؛ `0` يجيب فورًا

يحدّد Content-Type مثل application/pdf النوع أيضًا.
wait: القيمة true تساوي 60؛ تصل الإجابة دائمًا خلال 105 ثوانٍ. عند الرفع، يجيب false بمجرد تخزين النص، مع ocr_pending.
الصفحة خارج pages لا تُقرأ ولا تمر عبر OCR؛ واستخدام pages على ملف بلا صفحات يعيد 400.

المخطط الكامل: رفع ملف.

الاستجابة

الحقل	المعنى
`file_id`، `name`، `type`	المعرّف المستخدم، والاسم، والنوع المقروء (`image` لكل صيغ الصور)
`state`	`queued` أو `parsing` أو `ocr` (لا يزال OCR يقرأ `ocr_pending`) أو `ready` أو `failed` مع `error`
`source_id`	مصدر الملفات في مساحة الأسماء؛ يبدأ به معرّف المستند
`ids`	مستند الملف الوحيد، `["<source_id>:<file_id>"]`، بمجرد `ready`
`uploaded_at`	ميلي ثانية بتوقيت Unix
`result`	`unchanged` عندما رُفع الملف نفسه بالاسم والبيانات الوصفية والخيارات نفسها من قبل؛ لا يُعاد قراءة شيء
`pages`	صفحات ملف PDF أو إطارات صورة
`ocr_failed`	صفحات لم يتمكن OCR من قراءتها بعد عدة محاولات؛ ارفع الملف مجددًا لإعادة المحاولة
`markdown`، `parts`، `without_text`	النتيجة

الحقول images_without_text وpages_without_text وpages_ocr وimages_ocr وsheets وslides وslides_without_text مُهملة: يقدّم parts وwithout_text المعلومات نفسها.

التحقق من ملف

GET /namespaces/:namespace/files/:id يعيد آخر رفع للملف، بالحقول نفسها؛ استعلم عنه دوريًا بعد 202.

curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"

const file = await reports.getFile("report.pdf");

الخيار	النوع	الوظيفة
`user`	string	المستخدم، لملف مرفوع مع `user`

المخطط الكامل: قراءة ملف.

المستندات المخزّنة

الملف مستند واحد، <source_id>:<file_id>؛ وصفحاته وشرائحه وصفوف أوراقه وأقسامه وصوره هي أجزاؤه.

أين	ما تحصل عليه
البحث	صفحة ملف PDF أو صورة، أو شريحة، أو نطاق صفوف في ورقة، نتيجةٌ مستقلة بالمعرّف `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1`
البحث في ملف نصي أو Markdown أو Word	نتيجة واحدة، هي الملف `<source_id>:<file_id>`، مع مقاطعه من أي موضع فيه
`metadata` في النتيجة	موضع جزئها، أو أول مقطع فيها، بحسب المفاتيح أدناه
`GET /namespaces/:namespace/documents/:id`	بمعرّف الملف، نص الملف كاملًا مع سطر فارغ بين الصفحات؛ وبمعرّف جزء، ذلك الجزء وحده

موضع الجزء

الملف	الموقع في البيانات الوصفية
PDF	`page`
Word، نص، Markdown	`part` و`heading`، و`lines` للنص
PowerPoint	`slide`
Excel، CSV، TSV	`sheet`، `rows`
صورة	`page`، و`frame`
صورة داخل Word	`image`، `heading`
صورة على شريحة	`slide`، `image`
مخطط بياني في ورقة	`sheet`

يحمل المستند أيضًا file وfile_id وfile_type وuploaded_at وmetadata الخاصة بالرفع، وocr: true عندما قرأه OCR. وقد يبقى الملف المرفوع سابقًا مستندًا لكل جزء، مثل <source_id>:<file_id>:page-1، حتى يُرفع مجددًا.

لكي	افعل
تستبدل ملفًا	ارفعه مجددًا بالمعرّف نفسه
تعيد المحاولة بأمان	الملف نفسه بالاسم والبيانات الوصفية والخيارات نفسها يجيب `unchanged`، دون الحاجة إلى `Idempotency-Key`
تبحث في ملف واحد	صفِّ على `{ "file_id": "report.pdf" }`
تبحث في صفحة واحدة	صفِّ على `{ "file_id": "report.pdf", "page": 3 }`
تفصل بين المستخدمين	ارفع مع `user`، وابحث مع `user`
تحذف الأصل	يُحتفظ به حتى تُحذف مساحة الأسماء أو مستخدمه

تحليل ملف

POST /parse يعيد الملف بصيغة Markdown ولا يخزّن شيئًا؛ يمكن لأي مفتاح التحليل، حتى مفتاح Models فقط.

curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));

Response

{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

الخيار	النوع	الوظيفة
`url`	string	في جسم JSON: عنوان URL بـ `https` على عنوان عام، يُجلب خلال 60 ثانية، حتى 20 MiB
`name`، `type`، `pages`، `password`، `layout`، `wait`		كما في الرفع

يصل جسم الطلب حتى 20 MiB، ويقرأ OCR حتى 100 صفحة؛ تحتفظ الصفحات اللاحقة بطبقة نصها.
لتحليل ملف JSON، أرسله كـ text/plain.

المخطط الكامل: تحليل ملف.

جلب تحليل

GET /parse/:id يُحتفظ بالتحليل الذي أجاب بـ 202 (state: "parsing") لمدة 24 ساعة: اجلبه حتى يصبح state هو done، أو failed مع error الخاص به.

curl

curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"

المخطط الكامل: قراءة تحليل.

النتيجة

الحقل	المعنى
`markdown`	الملف كاملًا؛ تبدأ كل صفحة وشريحة وورقة بـ `<!-- page 3 -->` أو `<!-- slide 4 -->` أو `<!-- sheet "Q3" -->`
`parts`	بترتيب القراءة، لكلٍّ منها `locator` و`markdown` و`ocr` و`confidence`
`parts[].locator`	`{"page": 3}` أو `{"slide": 4, "image": 1}` أو `{"sheet": "Q3", "rows": "2-41"}` أو `{"part": 2, "heading": "..."}`
`parts[].ocr`	قُرئ بـ OCR من صورة الصفحة، لا من طبقة نصها
`parts[].confidence`	درجة يقين OCR، من 0 إلى 1؛ `null` عندما لم يقدّم OCR قيمة (معظم الصفحات الرقمية الأصل)
`without_text`	`pages` و`slides` و`images` التي لا تحتوي نصًا، وكل صورة مع `reason` الخاص بها

قواعد Markdown موجودة في أنواع الملفات.

الأخطاء

الخطأ	متى
`400 invalid_request`	خيار غير صالح: `pages` على ملف بلا صفحات، أو `wait` أكبر من 300، أو `metadata` ليس كائن JSON، أو عنوان URL ليس `https` على عنوان عام
`400 fetch_failed`	لم يُجب عنوان URL بـ `200` مع الملف
`404 parse_not_found`	لا يوجد تحليل بهذا المعرّف أجاب بـ `202` خلال آخر 24 ساعة
`409 file_replaced`	حُذف الملف أثناء انتظار الإجابة
`409 user_purging`	المستخدم قيد الحذف
`413 payload_too_large`	أكبر من 512 MiB (الرفع) أو 20 MiB (التحليل، أو مع `password`)
`415 unsupported_file`	نوع غير مدعوم، أو ليس `type` المُعلَن؛ توضّح الرسالة الصيغة التي يجب حفظه بها
`422 password_protected`	الملف محمي بكلمة مرور: أرسلها كـ `password`
`422 unreadable_file`	الملف تالف
`422 no_text`	لا تحتوي أي صفحة أو ورقة أو شريحة أو فقرة أو صورة على نص
`503 files_unavailable`	يتعذّر تخزين الملفات حاليًا؛ أعد المحاولة لاحقًا

ينتهي الملف الذي يتجاوز 5,000 صفحة أو ورقة أو شريحة بحالة failed مع too_large.

البدء

الأساسيات

الملفات

المزامنة

النماذج

الأدوات

الملفات

رفع ملف

الخيارات

الاستجابة

التحقق من ملف

المستندات المخزّنة

موضع الجزء

تحليل ملف

جلب تحليل

النتيجة

الأخطاء

​رفع ملف

​الخيارات

​الاستجابة

​التحقق من ملف

​المستندات المخزّنة

​موضع الجزء

​تحليل ملف

​جلب تحليل

​النتيجة

​الأخطاء

رفع ملف

الخيارات

الاستجابة

التحقق من ملف

المستندات المخزّنة

موضع الجزء

تحليل ملف

جلب تحليل

النتيجة

الأخطاء