توثيق واجهة Fileverity API

مرجع API

جميع نقاط نهاية Fileverity API مع المعلمات ومخططات الطلبات والاستجابات ورموز الأخطاء والأمثلة، مولَّدة من مواصفة OpenAPI 3.1.

عرض بصيغة Markdownآخر تحديث: 2026-11-04

يُولَّد هذا المرجع من وثيقة OpenAPI 3.1 الخاصة بـ API، المتاحة على https://api.fileverity.com/v1/openapi.json، ولذلك يطابق API دائمًا. وللاطلاع على المفاهيم والأدلة، ابدأ من صفحة نظرة عامة.

الاصطلاحات

عنوان URL الأساسي: https://api.fileverity.com/v1. صادِق على كل طلب باستخدام Authorization: Bearer <key>. تشترك الأخطاء في صيغة واحدة موصوفة في الأخطاء. تحمل كل استجابة الترويسة x-request-id، وتحمل الاستجابات المصادَق عليها ترويسات حدود المعدّل الموصوفة في حدود المعدّل والترويسات. وتُفتح الكائنات المتداخلة في أقسام قابلة للطي أسفل الجدول.

كشف النصوص

كشف النص المكتوب بالذكاء الاصطناعي

POST https://api.fileverity.com/v1/text/detections

يصنّف النص العادي على أنه مكتوب بالذكاء الاصطناعي أو مكتوب جزئيًا بالذكاء الاصطناعي أو كتبه إنسان، ويعيد الفقرات المكتوبة بالذكاء الاصطناعي. يُقيَّم النص ثم يُحذف ولا يُخزَّن. تحتسب الفوترة نقاط ترميز Unicode بوحدات قدر كل منها 1,000 حرف، ويُقرَّب الناتج للأعلى في كل طلب. ولا تُحتسب رسوم على الطلبات المرفوضة قبل التقييم. وتعيد مفاتيح الاختبار نتيجة ثابتة تفيد بأن النص كتبه إنسان دون رسوم.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`Idempotency-Key`	الترويسة	string	لا	مفتاح فريد من 255 حرفًا كحد أقصى. يعيد تكرار الطلب بالمفتاح ومحتوى الطلب نفسيهما خلال 24 ساعة الاستجابة الأولى مع الترويسة idempotent-replayed: true؛ أما المفتاح نفسه مع محتوى طلب مختلف فيعيد 409.

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`model`	string	لا	معرّف النموذج أو معرّف النسخة المؤرَّخة. القيمة الافتراضية `"fvdoc-3-text"`.
`text`	string	نعم	نص عادي، لا يقل عن 100 كلمة ولا يزيد على 100,000 حرف.
`language`	إحدى القيم: `"en"`، `"fr"`، `"de"`، `"es"`، `"zh"`، `null`	لا	رمز ISO 639-1. يُكتشف تلقائيًا عند عدم تحديده. القيمة الافتراضية `null`.

الاستجابات

الحالة	الوصف	المحتوى
200	نتيجة الكشف.	`TextDetection`
400	طلب غير صالح. رموز الأخطاء: invalid_json، missing_parameter، text_too_short، unsupported_language، invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
402	لا يكفي الرصيد أو حد الإنفاق الشهري للمفتاح لتغطية الطلب. رموز الأخطاء: insufficient_balance، spend_limit_reached.	`Error`
404	المورد غير موجود. رموز الأخطاء: model_not_found.	`Error`
409	تعارض مع الحالة الحالية. رموز الأخطاء: idempotency_mismatch، idempotency_in_progress.	`Error`
413	جرى تجاوز حد الحجم. رموز الأخطاء: text_too_long.	`Error`
415	نوع وسائط أو صيغة ملف غير مدعومة. رموز الأخطاء: unsupported_media_type.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`
502	تعذّر إكمال التحليل؛ لا تُحتسب رسوم. رموز الأخطاء: analysis_failed.	`Error`
503	الخدمة غير متاحة مؤقتًا أو أن السعة المتاحة مستخدمة بالكامل؛ لا تُحتسب رسوم. أعد المحاولة بعد عدد الثواني المذكور في الترويسة retry-after. رموز الأخطاء: service_unavailable.	`Error`

الاستجابة 200: TextDetection

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"text.detection"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`model`	string	نعم	النسخة المؤرَّخة التي أنتجت النتيجة.
`livemode`	boolean	نعم	القيمة false لمفاتيح الاختبار.
`language`	إحدى القيم: `"en"`، `"fr"`، `"de"`، `"es"`، `"zh"`	نعم
`verdict`	إحدى القيم: `"ai"`، `"mixed"`، `"human"`	نعم	ai: يبدو النص مكتوبًا بالذكاء الاصطناعي من أوله إلى آخره؛ mixed: فقرات مكتوبة بالذكاء الاصطناعي ضمن نص كتبه إنسان؛ human: لم يُعثر على أي فقرة مكتوبة بالذكاء الاصطناعي.
`score`	number	نعم	درجة النموذج لأكثر الفقرات شبهًا بالنص المكتوب بالذكاء الاصطناعي. الحد الأدنى 0. الحد الأقصى 1.
`ai_fraction`	number	نعم	نسبة النص المُقيَّم الواقعة ضمن مقاطع مكتوبة بالذكاء الاصطناعي. الحد الأدنى 0. الحد الأقصى 1.
`segments`	array من object	نعم	الفقرات المكتوبة بالذكاء الاصطناعي، على هيئة إزاحات في النص المُرسَل بنقاط ترميز Unicode. الحدود تقريبية وقد تشمل جملًا مجاورة.
`usage`	object	نعم

حقول segments

الحقل	النوع	مطلوب	الوصف
`start`	integer	نعم
`end`	integer	نعم	غير مشمولة.
`score`	number	نعم	الحد الأدنى 0. الحد الأقصى 1.

حقول usage

الحقل	النوع	مطلوب	الوصف
`characters`	integer	نعم	نقاط ترميز Unicode التي جرى تقييمها.
`free_characters`	integer	نعم	الأحرف التي يغطيها رصيد البدء المجاني ولا تُحتسب عليها رسوم.
`billed_units`	integer	نعم	وحدات قدر كل منها 1,000 حرف جرى احتسابها فعليًا بعد استبعاد الأحرف المجانية؛ والتكلفة هي حاصل ضرب billed_units في سعر الوحدة.

رموز الأخطاء

الرمز	الحالة
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`text_too_short`	400
`text_too_long`	413
`unsupported_language`	400
`model_not_found`	404
`insufficient_balance`	402
`spend_limit_reached`	402
`service_unavailable`	503
`analysis_failed`	502
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/text/detections \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d "$(jq -Rs '{text: .}' essay.txt)"

{  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": true,  "language": "en",  "verdict": "mixed",  "score": 0.97,  "ai_fraction": 0.41,  "segments": [    {      "start": 212,      "end": 433,      "score": 0.97    },    {      "start": 579,      "end": 790,      "score": 0.93    }  ],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

الملفات

رفع ملف

POST https://api.fileverity.com/v1/files

يرفع ملفًا لتحليله. أرسل الملفات التي لا يتجاوز حجمها 4 ميغابايت بصيغة multipart/form-data في الحقل file؛ وتحمل الاستجابة الحالة uploaded. أما الملفات الأكبر من 4 ميغابايت فيجب رفعها باستخدام عنوان URL موقّع مسبقًا. أرسل JSON يحتوي على filename وcontent_type وbytes (للمستندات حتى 50 ميغابايت)؛ وتحمل الاستجابة الحالة pending وكائن upload يتضمن عنوان URL موقّعًا مسبقًا: أرسل بايتات الملف إليه بالطريقة PUT مع الترويسات المحددة قبل انتهاء صلاحيته. ويُحذف الملف عند بدء التحليل وبعد 24 ساعة على أبعد تقدير. ويمكن أن تحتفظ مساحة العمل بما يصل إلى 50 ملفًا غير منتهي الصلاحية و200 ميغابايت في كل وضع في الوقت نفسه.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`Idempotency-Key`	الترويسة	string	لا	مفتاح فريد من 255 حرفًا كحد أقصى. يعيد تكرار الطلب بالمفتاح ومحتوى الطلب نفسيهما خلال 24 ساعة الاستجابة الأولى مع الترويسة idempotent-replayed: true؛ أما المفتاح نفسه مع محتوى طلب مختلف فيعيد 409.

محتوى الطلب: multipart/form-data، مطلوب

الحقل	النوع	مطلوب	الوصف
`file`	string	نعم	الصيغة binary.

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`filename`	string	لا
`content_type`	string	نعم	نوع MIME للملف، مثل image/jpeg أو application/pdf.
`bytes`	integer	نعم	الحجم الدقيق بالبايت. الحد الأدنى 1. الحد الأقصى 52,428,800.

الاستجابات

الحالة	الوصف	المحتوى
201	الملف.	`File`
400	طلب غير صالح. رموز الأخطاء: invalid_json، missing_parameter، invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
409	تعارض مع الحالة الحالية. رموز الأخطاء: idempotency_mismatch، idempotency_in_progress.	`Error`
413	جرى تجاوز حد الحجم. رموز الأخطاء: file_too_large.	`Error`
415	نوع وسائط أو صيغة ملف غير مدعومة. رموز الأخطاء: unsupported_media_type، unsupported_file.	`Error`
422	لا يمكن معالجة الملف. رموز الأخطاء: invalid_file.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: pending_files_limit، rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 201: File

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"file"`	نعم
`filename`	string أو null	نعم
`bytes`	integer أو null	نعم
`content_type`	string	نعم
`status`	إحدى القيم: `"pending"`، `"uploaded"`	نعم	تبقى pending إلى أن تصل البايتات المرسلة إلى عنوان URL الموقّع مسبقًا.
`livemode`	boolean	نعم	لا تظهر الملفات إلا للمفاتيح من الوضع نفسه.
`created`	integer	نعم	طابع زمني بصيغة Unix.
`expires_at`	integer	نعم	طابع زمني بصيغة Unix يُحذف الملف بعده.
`upload`	object	لا	موجود في الاستجابة لطلب رفع بصيغة JSON.

حقول upload

الحقل	النوع	مطلوب	الوصف
`url`	string	نعم	تحصل مفاتيح الاختبار على عنوان URL تجريبي (test: true)؛ ولا يُرفع شيء ولا يُخزَّن.
`method`	`"PUT"`	نعم
`headers`	object من string	نعم
`expires_at`	integer	نعم	طابع زمني بصيغة Unix.
`test`	`true`	لا

رموز الأخطاء

الرمز	الحالة
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`unsupported_file`	415
`invalid_file`	422
`file_too_large`	413
`pending_files_limit`	429
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -F file=@claim-photo.jpg

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "filename": "claim-photo.jpg",  "bytes": 2481920,  "content_type": "image/jpeg",  "status": "uploaded",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400}

جلب ملف

GET https://api.fileverity.com/v1/files/{id}

يعيد الملف ويبيّن ما إذا كانت بايتاته قد وصلت.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`id`	المسار	string	نعم	معرّف الملف.

الاستجابات

الحالة	الوصف	المحتوى
200	الملف.	`File`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: not_found.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: File

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"file"`	نعم
`filename`	string أو null	نعم
`bytes`	integer أو null	نعم
`content_type`	string	نعم
`status`	إحدى القيم: `"pending"`، `"uploaded"`	نعم	تبقى pending إلى أن تصل البايتات المرسلة إلى عنوان URL الموقّع مسبقًا.
`livemode`	boolean	نعم	لا تظهر الملفات إلا للمفاتيح من الوضع نفسه.
`created`	integer	نعم	طابع زمني بصيغة Unix.
`expires_at`	integer	نعم	طابع زمني بصيغة Unix يُحذف الملف بعده.
`upload`	object	لا	موجود في الاستجابة لطلب رفع بصيغة JSON.

حقول upload

الحقل	النوع	مطلوب	الوصف
`url`	string	نعم	تحصل مفاتيح الاختبار على عنوان URL تجريبي (test: true)؛ ولا يُرفع شيء ولا يُخزَّن.
`method`	`"PUT"`	نعم
`headers`	object من string	نعم
`expires_at`	integer	نعم	طابع زمني بصيغة Unix.
`test`	`true`	لا

رموز الأخطاء

الرمز	الحالة
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "filename": "claim-photo.jpg",  "bytes": 2481920,  "content_type": "image/jpeg",  "status": "uploaded",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400}

حذف ملف

DELETE https://api.fileverity.com/v1/files/{id}

يحذف ملفًا مرفوعًا والبايتات المخزَّنة منه.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`id`	المسار	string	نعم	معرّف الملف.

الاستجابات

الحالة	الوصف	المحتوى
200	حُذف الملف.	`FileDeleted`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: not_found.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: FileDeleted

الحقل	النوع	مطلوب
`id`	string	نعم
`object`	`"file"`	نعم
`deleted`	`true`	نعم

رموز الأخطاء

الرمز	الحالة
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl -X DELETE https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "deleted": true}

التحليلات

إنشاء تحليل

POST https://api.fileverity.com/v1/analyses

يحلّل ملفًا مرفوعًا باستخدام fvimg-2 (للصور) أو fvdoc-3 (للمستندات). التحليل هو فحص واحد لصورة أو مستند. تكون الاستجابة 202 بالحالة processing؛ وتصل النتيجة عبر Webhook أو بالاستعلام المتكرر عبر GET /analyses/{id}. أرسل Prefer: wait=N (حتى 60 ثانية) لإبقاء الطلب معلّقًا إلى أن تصبح النتيجة جاهزة؛ ويعيد التحليل المنتهي الاستجابة 200. يُحجز السعر عند إنشاء التحليل ويُحرَّر إذا فشل التحليل أو أُلغي. وتُحفظ النتائج 7 أيام. وعندما تكون السعة المتاحة مستخدمة بالكامل تعيد API الاستجابة 503 service_unavailable مع الترويسة retry-after ولا تحتسب أي رسوم: أعد المحاولة بقيمة Idempotency-Key نفسها، وشغّل تحليلات الصور واحدًا تلو الآخر للحصول على أعلى إنتاجية. وتعيد مفاتيح الاختبار نتيجة نموذجية ولا تُحتسب عليها رسوم أبدًا؛ ولا يتضمن التقرير النموذجي سوى بضعة حقول.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`Idempotency-Key`	الترويسة	string	لا	مفتاح فريد من 255 حرفًا كحد أقصى. يعيد تكرار الطلب بالمفتاح ومحتوى الطلب نفسيهما خلال 24 ساعة الاستجابة الأولى مع الترويسة idempotent-replayed: true؛ أما المفتاح نفسه مع محتوى طلب مختلف فيعيد 409.
`Prefer`	الترويسة	string	لا	يُبقي wait=N الطلب معلّقًا حتى N ثانية (60 كحد أقصى) إلى أن ينتهي التحليل.

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`model`	إحدى القيم: `"fvimg-2"`، `"fvimg-2-2026-10-30"`، `"fvdoc-3"`، `"fvdoc-3-2026-11-03"`	نعم	معرّف النموذج أو معرّف النسخة المؤرَّخة. يحلّل fvimg-2 الصور، ويحلّل fvdoc-3 المستندات.
`file`	string	نعم	معرّف ملف مرفوع.
`metadata`	object من string	لا	حتى 16 زوجًا (مفتاح وقيمة) من النصوص (طول المفتاح حتى 40 حرفًا وطول القيمة حتى 500)، تُعاد مع التحليل وفي Webhooks.
`options`	object	لا

حقول options

الحقل	النوع	مطلوب	الوصف
`password`	string	لا	كلمة مرور المستند المشفّر. الحد الأقصى للطول 256.
`locale`	إحدى القيم: `"en"`، `"fr"`، `"de"`، `"es"`، `"zh"`، `"vi"`، `"ar"`	لا	لغة مؤشرات المستند. القيمة الافتراضية `"en"`.

الاستجابات

الحالة	الوصف	المحتوى
200	التحليل المنتهي.	`Analysis`
202	التحليل قيد المعالجة.	`Analysis`
400	طلب غير صالح. رموز الأخطاء: invalid_json، missing_parameter، file_not_found، invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
402	لا يكفي الرصيد أو حد الإنفاق الشهري للمفتاح لتغطية الطلب. رموز الأخطاء: insufficient_balance، spend_limit_reached.	`Error`
404	المورد غير موجود. رموز الأخطاء: model_not_found.	`Error`
409	تعارض مع الحالة الحالية. رموز الأخطاء: idempotency_mismatch، idempotency_in_progress.	`Error`
413	جرى تجاوز حد الحجم. رموز الأخطاء: file_too_large، too_many_pixels، too_many_pages، document_too_long.	`Error`
415	نوع وسائط أو صيغة ملف غير مدعومة. رموز الأخطاء: unsupported_media_type، unsupported_file.	`Error`
422	لا يمكن معالجة الملف. رموز الأخطاء: invalid_file، password_required، wrong_password، not_examinable.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`
502	تعذّر إكمال التحليل؛ لا تُحتسب رسوم. رموز الأخطاء: analysis_failed.	`Error`
503	الخدمة غير متاحة مؤقتًا أو أن السعة المتاحة مستخدمة بالكامل؛ لا تُحتسب رسوم. أعد المحاولة بعد عدد الثواني المذكور في الترويسة retry-after. رموز الأخطاء: service_unavailable.	`Error`

الاستجابة 200: Analysis

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"analysis"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`model`	string	نعم	النسخة المؤرَّخة التي أنتجت النتيجة.
`livemode`	boolean	نعم
`status`	إحدى القيم: `"processing"`، `"succeeded"`، `"failed"`، `"canceled"`	نعم
`file`	object	نعم
`report_id`	string أو null	نعم	رقم التقرير القابل للتحقق، FV-XXXX-XXXX-XXXX.
`report_url`	string أو null	نعم	صفحة التحقق العامة الخاصة بالتقرير.
`summary`	`ImageSummary` أو `DocumentSummary` أو null	نعم	الحكم المختصر الثابت: ImageSummary للصور، وDocumentSummary للمستندات، وnull إلى أن ينجح التحليل.
`result`	object أو null	نعم	يوجد ما إن تصبح قيمة status هي succeeded وإلى أن تنتهي صلاحية النتيجة.
`error`	object أو null	نعم
`progress`	object أو null	نعم
`usage`	object	نعم
`metadata`	object أو null	نعم
`completed_at`	integer أو null	نعم
`expires_at`	integer أو null	نعم	طابع زمني بصيغة Unix تُحذف النتيجة بعده.

حقول file

الحقل	النوع	مطلوب
`name`	string أو null	لا
`bytes`	integer أو null	لا
`format`	string أو null	لا

حقول summary (ImageSummary)

الحقل	النوع	مطلوب	الوصف
`level`	إحدى القيم `"L0"` أو `"L1"` أو `"L2"` أو `"L3"` أو `"L4"` أو `"L5"`	نعم	مستوى المخاطر، من L0 إلى L5.
`assessment`	إحدى القيم: `"authentic_untouched"`، `"authentic_locally_edited"`، `"ai_generated"`، `"undetermined"`	نعم
`action`	إحدى القيم: `"accept"`، `"review"`، `"reject"`، `"resubmit"`	نعم
`ai`	إحدى القيم: `"labelled"`، `"very_likely"`، `"suspected"`، `"undecided"`، `"low"`، `"very_low"`، `"not_evaluated"`	نعم	المؤشر المتعلق بالتوليد بالذكاء الاصطناعي.
`edit`	إحدى القيم: `"detected"`، `"suspected"`، `"suspected_record"`، `"review"`، `"generative"`، `"minor"`، `"none"`، `"not_applicable"`، `"not_evaluated"`	نعم	المؤشر المتعلق بالتعديل الموضعي.

حقول summary (DocumentSummary)

الحقل	النوع	مطلوب	الوصف
`kind`	`"docpro"`	نعم
`level`	إحدى القيم `"L0"` أو `"L1"` أو `"L2"` أو `"L3"` أو `"L4"` أو `"L5"`	نعم	مستوى المخاطر، من L0 إلى L5.
`action`	إحدى القيم `"accept"` أو `"note"` أو `"review"` أو `"reject"` أو `"resubmit"`	نعم	note: قارن المحتوى المكتوب بالذكاء الاصطناعي المعلَّم في التقرير بسياستك.
`reason`	string أو null	نعم	المؤشر أو الحالة التي يستند إليها المستوى، مثل clean أو incomplete، أو معرّف مؤشر.
`findings`	array من string	نعم	معرّفات المؤشرات المهمة.
`pages`	integer	نعم	عدد صفحات المستند.
`images`	integer	نعم	عدد الصور المضمَّنة التي جرى فحصها.
`text`	إحدى القيم: `"ai_generated"`، `"mixed"`، `"human"`، `"inconclusive"`، `null`	نعم	الحكم على نص المستند، أو null عندما لم يُقيَّم النص.
`strong`	`true`	لا	يوجد عندما يكون أحد المؤشرات المدرجة قويًا.

حقول result

الحقل	النوع	مطلوب	الوصف
`report`	`ImageReport` أو `DocumentReport`	لا	التقرير الكامل. قيمة report.schema هي fileverity.report/1 للصور وfileverity.docpro/1 للمستندات.
`stamped_at`	integer أو null	لا	طابع زمني بصيغة Unix للطابع الزمني الصادر للتقرير وفق RFC 3161، أو null.

حقول report (ImageReport)

الحقل	النوع	مطلوب	الوصف
`schema`	`"fileverity.report/1"`	نعم
`id`	string	نعم	رقم التقرير، FV-XXXX-XXXX-XXXX.
`sample`	`true`	لا	موجود في التقارير النموذجية الثابتة التي تعيدها مفاتيح الاختبار.
`issuedAt`	string	لا	وقت إصدار التقرير، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time.
`issuer`	object	لا	الجهة التي أصدرت التقرير.
`file`	object	لا	الصورة المفحوصة.
`pro`	object	لا	الحكم. القيم نفسها الواردة في summary، مع reason.
`score`	integer أو null	لا	درجة الأصالة من 0 إلى 100 بخطوات قدرها 5: مدى قوة الأدلة التي تدعم كون الصورة التقاطًا أصيلًا غير معدَّل. وتكون null عند عدم التقييم.
`confidence`	إحدى القيم `"high"` أو `"medium"` أو `"low"`	لا	مقدار ما يتيح هذا الملف للتحليل إثباته. وغالبًا ما يعكس انخفاض الثقة الملف نفسه، مثل انخفاض الدقة أو الضغط الشديد.
`questions`	object	لا	الأسئلة الثلاثة التي يجيب عنها التقرير.
`generator`	object أو null	لا	أداة التوليد بالذكاء الاصطناعي المنسوبة إلى الصورة، أو null.
`regions`	array من object	لا	المناطق المعلَّمة، بالبكسل في الصورة المعروضة.
`provenance`	object	لا	ما تذكره سجلات الملف نفسه عن منشئه.
`digest`	string	لا	قيمة تجزئة محتوى التقرير، تستخدمها صفحة التحقق.

حقول issuer

الحقل	النوع	مطلوب	الوصف
`name`	string	لا
`operator`	string	لا
`verify`	string	لا	صفحة التحقق العامة الخاصة بالتقرير.

حقول file

الحقل	النوع	مطلوب	الوصف
`name`	string أو null	لا
`sha256`	string	لا	قيمة تجزئة SHA-256 للملف المفحوص، بالنظام السداسي العشري.
`bytes`	integer	لا
`width`	integer	لا	العرض بالبكسل كما يظهر.
`height`	integer	لا	الارتفاع بالبكسل كما يظهر.
`format`	string	لا

حقول pro

الحقل	النوع	مطلوب	الوصف
`level`	إحدى القيم `"L0"` أو `"L1"` أو `"L2"` أو `"L3"` أو `"L4"` أو `"L5"`	لا	مستوى المخاطر، من L0 إلى L5.
`action`	إحدى القيم: `"accept"`، `"review"`، `"reject"`، `"resubmit"`	لا
`assessment`	إحدى القيم: `"authentic_untouched"`، `"authentic_locally_edited"`، `"ai_generated"`، `"undetermined"`	لا
`reason`	string أو null	لا

حقول questions

الحقل	النوع	مطلوب
`ai`	object	لا
`edit`	object	لا
`source`	object	لا

حقول ai

الحقل	النوع	مطلوب	الوصف
`key`	إحدى القيم: `"labelled"`، `"very_likely"`، `"suspected"`، `"undecided"`، `"low"`، `"very_low"`، `"not_evaluated"`	لا
`basis`	إحدى القيم: `"verified"`، `"detected"`، `"declared"`، `null`	لا	ما تستند إليه الإجابة.
`strength`	إحدى القيم: `"strong"`، `"moderate"`، `"limited"`، `null`	لا	مدى قوة دعم الأدلة للإجابة.
`likelihood`	integer أو null	لا	احتمال التوليد بالذكاء الاصطناعي من 0 إلى 100 بخطوات قدرها 5، أو null.

حقول edit

الحقل	النوع	مطلوب	الوصف
`key`	إحدى القيم: `"detected"`، `"suspected"`، `"suspected_record"`، `"review"`، `"generative"`، `"minor"`، `"none"`، `"not_applicable"`، `"not_evaluated"`	لا
`basis`	إحدى القيم: `"verified"`، `"detected"`، `"declared"`، `null`	لا	ما تستند إليه الإجابة.
`strength`	إحدى القيم: `"strong"`، `"moderate"`، `"limited"`، `null`	لا	مدى قوة دعم الأدلة للإجابة.
`regions`	integer	لا	عدد المناطق المعلَّمة.

حقول source

الحقل	النوع	مطلوب	الوصف
`key`	string	لا
`basis`	إحدى القيم: `"verified"`، `"detected"`، `"declared"`، `null`	لا	ما تستند إليه الإجابة.
`strength`	إحدى القيم: `"strong"`، `"moderate"`، `"limited"`، `null`	لا	مدى قوة دعم الأدلة للإجابة.
`signer`	string أو null	لا
`aiClaim`	boolean	لا	ما إذا كانت سجلات الملف نفسه تفيد بأنه مولَّد بالذكاء الاصطناعي.

حقول generator

الحقل	النوع	مطلوب	الوصف
`name`	string	لا
`basis`	string	لا	كيف جرى تحديد أداة التوليد.

حقول regions

الحقل	النوع	مطلوب
`id`	string	لا
`x`	integer	لا
`y`	integer	لا
`w`	integer	لا
`h`	integer	لا
`strength`	إحدى القيم: `"high"`، `"medium"`	لا

حقول provenance

الحقل	النوع	مطلوب	الوصف
`credentials`	إحدى القيم: `"valid"`، `"unverified"`، `"issues"`، `"invalid"`، `"removed"`، `"none"`	لا	حالة Content Credentials.
`signer`	string أو null	لا
`software`	array من string	لا	البرمجيات المذكورة في سجلات الملف.
`camera`	string أو null	لا
`captured`	string أو null	لا	وقت الالتقاط المسجَّل في الملف، إن وُجد.

حقول report (DocumentReport)

الحقل	النوع	مطلوب	الوصف
`schema`	`"fileverity.docpro/1"`	نعم
`id`	string	نعم	رقم التقرير، FV-XXXX-XXXX-XXXX.
`sample`	`true`	لا	موجود في التقارير النموذجية الثابتة التي تعيدها مفاتيح الاختبار.
`issuedAt`	string	لا	وقت إصدار التقرير، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time.
`receivedAt`	string	لا	وقت استلام الملف، بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). الصيغة date-time.
`issuer`	object	لا	الجهة التي أصدرت التقرير.
`file`	object	لا	المستند المفحوص.
`level`	إحدى القيم `"L0"` أو `"L1"` أو `"L2"` أو `"L3"` أو `"L4"` أو `"L5"`	لا	مستوى المخاطر، من L0 إلى L5.
`action`	إحدى القيم `"accept"` أو `"note"` أو `"review"` أو `"reject"` أو `"resubmit"`	لا
`reason`	string أو null	لا	المؤشر أو الحالة التي بُني عليها المستوى.
`findings`	array من object	لا	المؤشرات التي بُني عليها المستوى، مع الصفحات والصور المضمَّنة التي يشير إليها كل منها.
`text`	object	لا	نتيجة نص المستند.
`images`	array من object	لا	الصور والرسومات المضمَّنة، مرقَّمة بحسب ترتيبها في المستند.
`structure`	object أو null	لا	سجل تعديلات الملف، أو null إذا لم يُفحص.
`provenance`	object	لا	ما تذكره سجلات الملف نفسه عن منشئه.
`digest`	string	لا	قيمة تجزئة محتوى التقرير، تستخدمها صفحة التحقق.

حقول issuer

الحقل	النوع	مطلوب	الوصف
`name`	string	لا
`operator`	string	لا
`verify`	string	لا	صفحة التحقق العامة الخاصة بالتقرير.

حقول file

الحقل	النوع	مطلوب	الوصف
`name`	string أو null	لا
`sha256`	string	لا	قيمة تجزئة SHA-256 للملف المفحوص، بالنظام السداسي العشري.
`bytes`	integer	لا
`format`	string	لا
`pages`	integer	لا
`textLayer`	إحدى القيم: `"present"`، `"partial"`، `"absent"`	لا	ما إذا كان المستند يحتوي على طبقة نصية.

حقول findings

الحقل	النوع	مطلوب	الوصف
`id`	string	لا
`basis`	إحدى القيم: `"verified"`، `"detected"`، `"declared"`	لا
`strength`	إحدى القيم: `"strong"`، `"moderate"`، `"limited"`	لا
`material`	boolean	لا	ما إذا كان المؤشر يُحتسب ضمن المستوى.
`pages`	array من integer	لا
`images`	array من integer	لا

حقول text

الحقل	النوع	مطلوب	الوصف
`status`	إحدى القيم: `"evaluated"`، `"insufficient_text"`، `"unsupported_language"`، `"no_text"`	لا
`verdict`	إحدى القيم: `"ai_generated"`، `"mixed"`، `"human"`، `"inconclusive"`	لا	يوجد عندما تكون قيمة status هي evaluated.
`words`	integer	لا
`languages`	array من string	لا
`passages`	integer	لا	عدد الفقرات المعلَّمة.

حقول images

الحقل	النوع	مطلوب
`n`	integer	لا
`pages`	array من integer	لا
`kind`	إحدى القيم: `"photo"`، `"graphic"`	لا
`width`	integer	لا
`height`	integer	لا
`level`	إحدى القيم: `"L0"`، `"L1"`، `"L2"`، `"L3"`، `"L4"`، `"L5"`، `null`	لا
`assessment`	إحدى القيم: `"authentic_untouched"`، `"authentic_locally_edited"`، `"ai_generated"`، `"undetermined"`، `null`	لا
`ai`	إحدى القيم: `"labelled"`، `"very_likely"`، `"suspected"`، `"undecided"`، `"low"`، `"very_low"`، `"not_evaluated"`، `null`	لا
`edit`	إحدى القيم: `"detected"`، `"suspected"`، `"suspected_record"`، `"review"`، `"generative"`، `"minor"`، `"none"`، `"not_applicable"`، `"not_evaluated"`، `null`	لا

حقول structure

الحقل	النوع	مطلوب
`revisions`	integer أو null	لا
`changedPages`	array من integer	لا
`addedPages`	integer	لا
`signatures`	integer	لا

حقول provenance

الحقل	النوع	مطلوب	الوصف
`credentials`	string	لا	حالة Content Credentials.
`signer`	string أو null	لا
`aiClaim`	boolean	لا	ما إذا كانت سجلات الملف نفسه تفيد بأنه مولَّد بالذكاء الاصطناعي.
`software`	array من string	لا
`created`	string أو null	لا
`modified`	string أو null	لا
`revisions`	integer أو null	لا
`signed`	boolean أو null	لا

حقول error

الحقل	النوع	مطلوب	الوصف
`code`	إحدى القيم: `"invalid_json"`، `"missing_parameter"`، `"invalid_parameter"`، `"text_too_short"`، `"text_too_long"`، `"unsupported_media_type"`، `"unsupported_language"`، `"file_not_found"`، `"unsupported_file"`، `"file_too_large"`، `"too_many_pixels"`، `"too_many_pages"`، `"document_too_long"`، `"invalid_file"`، `"password_required"`، `"wrong_password"`، `"not_examinable"`، `"missing_api_key"`، `"invalid_api_key"`، `"insufficient_balance"`، `"spend_limit_reached"`، `"not_found"`، `"model_not_found"`، `"not_cancelable"`، `"canceled"`، `"idempotency_mismatch"`، `"idempotency_in_progress"`، `"pending_files_limit"`، `"rate_limited"`، `"internal_error"`، `"analysis_failed"`، `"service_unavailable"`	لا
`message`	string	لا

حقول progress

الحقل	النوع	مطلوب	الوصف
`stage`	إحدى القيم: `"queued"`، `"reading"`، `"analyzing"`، `"reporting"`	لا
`done`	integer	لا	عدد الوحدات المنجزة في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`total`	integer	لا	عدد الوحدات في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`position`	integer	لا	الترتيب في قائمة الانتظار ما دامت المرحلة في الانتظار.

حقول usage

الحقل	النوع	مطلوب	الوصف
`amount`	integer	لا	الرسوم بالسنتات؛ 0 لفحوصات رصيد البدء المجاني ولحالات الفشل.
`currency`	`"usd"`	لا
`funding`	إحدى القيم: `"trial"`، `"balance"`، `null`	لا

رموز الأخطاء

الرمز	الحالة
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`model_not_found`	404
`file_not_found`	400
`unsupported_file`	415
`invalid_file`	422
`file_too_large`	413
`too_many_pixels`	413
`too_many_pages`	413
`document_too_long`	413
`password_required`	422
`wrong_password`	422
`not_examinable`	422
`insufficient_balance`	402
`spend_limit_reached`	402
`service_unavailable`	503
`analysis_failed`	502
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/analyses \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Prefer: wait=60" \  -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvimg-2-2026-10-30",  "livemode": true,  "status": "succeeded",  "file": {    "name": "claim-photo.jpg",    "bytes": 2481920,    "format": "jpeg"  },  "report_id": "FV-7K2M-9QXD-4T8R",  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",  "summary": {    "level": "L2",    "assessment": "authentic_untouched",    "action": "accept",    "ai": "very_low",    "edit": "none"  },  "result": {    "report": {      "schema": "fileverity.report/1",      "id": "FV-7K2M-9QXD-4T8R"    },    "stamped_at": 1793700130  },  "error": null,  "progress": null,  "usage": {    "amount": 199,    "currency": "usd",    "funding": "balance"  },  "metadata": {    "order_id": "A-10492"  },  "completed_at": 1793700131,  "expires_at": 1794304931}

عرض قائمة التحليلات

GET https://api.fileverity.com/v1/analyses

يعرض تحليلات الصور والمستندات في مساحة عملك، بدءًا من الأحدث. وتحصل مفاتيح الاختبار دائمًا على قائمة فارغة.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`limit`	الاستعلام	integer	لا	القيمة الافتراضية `20`. الحد الأدنى 1. الحد الأقصى 100.
`starting_after`	الاستعلام	string	لا	مؤشر التصفح: قيمة next_cursor من الصفحة السابقة.
`type`	الاستعلام	إحدى القيم: `"image"`، `"document"`	لا

الاستجابات

الحالة	الوصف	المحتوى
200	صفحة من التحليلات.	`AnalysisList`
400	طلب غير صالح. رموز الأخطاء: invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: AnalysisList

الحقل	النوع	مطلوب	الوصف
`object`	`"list"`	نعم
`data`	array من `Analysis`	نعم
`has_more`	boolean	نعم
`next_cursor`	string أو null	نعم	مرّره في starting_after للحصول على الصفحة التالية.

حقول data

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"analysis"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`model`	string	نعم	النسخة المؤرَّخة التي أنتجت النتيجة.
`livemode`	boolean	نعم
`status`	إحدى القيم: `"processing"`، `"succeeded"`، `"failed"`، `"canceled"`	نعم
`file`	object	نعم
`report_id`	string أو null	نعم	رقم التقرير القابل للتحقق، FV-XXXX-XXXX-XXXX.
`report_url`	string أو null	نعم	صفحة التحقق العامة الخاصة بالتقرير.
`summary`	`ImageSummary` أو `DocumentSummary` أو null	نعم	الحكم المختصر الثابت: ImageSummary للصور، وDocumentSummary للمستندات، وnull إلى أن ينجح التحليل.
`result`	object أو null	نعم	يوجد ما إن تصبح قيمة status هي succeeded وإلى أن تنتهي صلاحية النتيجة.
`error`	object أو null	نعم
`progress`	object أو null	نعم
`usage`	object	نعم
`metadata`	object أو null	نعم
`completed_at`	integer أو null	نعم
`expires_at`	integer أو null	نعم	طابع زمني بصيغة Unix تُحذف النتيجة بعده.

حقول file

الحقل	النوع	مطلوب
`name`	string أو null	لا
`bytes`	integer أو null	لا
`format`	string أو null	لا

حقول result

الحقل	النوع	مطلوب	الوصف
`report`	`ImageReport` أو `DocumentReport`	لا	التقرير الكامل. قيمة report.schema هي fileverity.report/1 للصور وfileverity.docpro/1 للمستندات.
`stamped_at`	integer أو null	لا	طابع زمني بصيغة Unix للطابع الزمني الصادر للتقرير وفق RFC 3161، أو null.

حقول error

الحقل	النوع	مطلوب	الوصف
`code`	إحدى القيم: `"invalid_json"`، `"missing_parameter"`، `"invalid_parameter"`، `"text_too_short"`، `"text_too_long"`، `"unsupported_media_type"`، `"unsupported_language"`، `"file_not_found"`، `"unsupported_file"`، `"file_too_large"`، `"too_many_pixels"`، `"too_many_pages"`، `"document_too_long"`، `"invalid_file"`، `"password_required"`، `"wrong_password"`، `"not_examinable"`، `"missing_api_key"`، `"invalid_api_key"`، `"insufficient_balance"`، `"spend_limit_reached"`، `"not_found"`، `"model_not_found"`، `"not_cancelable"`، `"canceled"`، `"idempotency_mismatch"`، `"idempotency_in_progress"`، `"pending_files_limit"`، `"rate_limited"`، `"internal_error"`، `"analysis_failed"`، `"service_unavailable"`	لا
`message`	string	لا

حقول progress

الحقل	النوع	مطلوب	الوصف
`stage`	إحدى القيم: `"queued"`، `"reading"`، `"analyzing"`، `"reporting"`	لا
`done`	integer	لا	عدد الوحدات المنجزة في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`total`	integer	لا	عدد الوحدات في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`position`	integer	لا	الترتيب في قائمة الانتظار ما دامت المرحلة في الانتظار.

حقول usage

الحقل	النوع	مطلوب	الوصف
`amount`	integer	لا	الرسوم بالسنتات؛ 0 لفحوصات رصيد البدء المجاني ولحالات الفشل.
`currency`	`"usd"`	لا
`funding`	إحدى القيم: `"trial"`، `"balance"`، `null`	لا

رموز الأخطاء

الرمز	الحالة
`invalid_parameter`	400
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl "https://api.fileverity.com/v1/analyses?limit=20&type=image" \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "object": "list",  "data": [    {      "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",      "object": "analysis",      "created": 1793700120,      "model": "fvimg-2-2026-10-30",      "livemode": true,      "status": "succeeded",      "file": {        "name": "claim-photo.jpg",        "bytes": 2481920,        "format": "jpeg"      },      "report_id": "FV-7K2M-9QXD-4T8R",      "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",      "summary": {        "level": "L2",        "assessment": "authentic_untouched",        "action": "accept",        "ai": "very_low",        "edit": "none"      },      "result": {        "report": {          "schema": "fileverity.report/1",          "id": "FV-7K2M-9QXD-4T8R"        },        "stamped_at": 1793700130      },      "error": null,      "progress": null,      "usage": {        "amount": 199,        "currency": "usd",        "funding": "balance"      },      "metadata": {        "order_id": "A-10492"      },      "completed_at": 1793700131,      "expires_at": 1794304931    }  ],  "has_more": false,  "next_cursor": null}

جلب تحليل

GET https://api.fileverity.com/v1/analyses/{id}

يعيد التحليل مع نتيجته متى نجح وإلى أن تنتهي صلاحيتها.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`id`	المسار	string	نعم	معرّف التحليل.

الاستجابات

الحالة	الوصف	المحتوى
200	التحليل.	`Analysis`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: not_found.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: Analysis

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"analysis"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`model`	string	نعم	النسخة المؤرَّخة التي أنتجت النتيجة.
`livemode`	boolean	نعم
`status`	إحدى القيم: `"processing"`، `"succeeded"`، `"failed"`، `"canceled"`	نعم
`file`	object	نعم
`report_id`	string أو null	نعم	رقم التقرير القابل للتحقق، FV-XXXX-XXXX-XXXX.
`report_url`	string أو null	نعم	صفحة التحقق العامة الخاصة بالتقرير.
`summary`	`ImageSummary` أو `DocumentSummary` أو null	نعم	الحكم المختصر الثابت: ImageSummary للصور، وDocumentSummary للمستندات، وnull إلى أن ينجح التحليل.
`result`	object أو null	نعم	يوجد ما إن تصبح قيمة status هي succeeded وإلى أن تنتهي صلاحية النتيجة.
`error`	object أو null	نعم
`progress`	object أو null	نعم
`usage`	object	نعم
`metadata`	object أو null	نعم
`completed_at`	integer أو null	نعم
`expires_at`	integer أو null	نعم	طابع زمني بصيغة Unix تُحذف النتيجة بعده.

حقول file

الحقل	النوع	مطلوب
`name`	string أو null	لا
`bytes`	integer أو null	لا
`format`	string أو null	لا

حقول result

الحقل	النوع	مطلوب	الوصف
`report`	`ImageReport` أو `DocumentReport`	لا	التقرير الكامل. قيمة report.schema هي fileverity.report/1 للصور وfileverity.docpro/1 للمستندات.
`stamped_at`	integer أو null	لا	طابع زمني بصيغة Unix للطابع الزمني الصادر للتقرير وفق RFC 3161، أو null.

حقول error

الحقل	النوع	مطلوب	الوصف
`code`	إحدى القيم: `"invalid_json"`، `"missing_parameter"`، `"invalid_parameter"`، `"text_too_short"`، `"text_too_long"`، `"unsupported_media_type"`، `"unsupported_language"`، `"file_not_found"`، `"unsupported_file"`، `"file_too_large"`، `"too_many_pixels"`، `"too_many_pages"`، `"document_too_long"`، `"invalid_file"`، `"password_required"`، `"wrong_password"`، `"not_examinable"`، `"missing_api_key"`، `"invalid_api_key"`، `"insufficient_balance"`، `"spend_limit_reached"`، `"not_found"`، `"model_not_found"`، `"not_cancelable"`، `"canceled"`، `"idempotency_mismatch"`، `"idempotency_in_progress"`، `"pending_files_limit"`، `"rate_limited"`، `"internal_error"`، `"analysis_failed"`، `"service_unavailable"`	لا
`message`	string	لا

حقول progress

الحقل	النوع	مطلوب	الوصف
`stage`	إحدى القيم: `"queued"`، `"reading"`، `"analyzing"`، `"reporting"`	لا
`done`	integer	لا	عدد الوحدات المنجزة في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`total`	integer	لا	عدد الوحدات في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`position`	integer	لا	الترتيب في قائمة الانتظار ما دامت المرحلة في الانتظار.

حقول usage

الحقل	النوع	مطلوب	الوصف
`amount`	integer	لا	الرسوم بالسنتات؛ 0 لفحوصات رصيد البدء المجاني ولحالات الفشل.
`currency`	`"usd"`	لا
`funding`	إحدى القيم: `"trial"`، `"balance"`، `null`	لا

رموز الأخطاء

الرمز	الحالة
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvimg-2-2026-10-30",  "livemode": true,  "status": "succeeded",  "file": {    "name": "claim-photo.jpg",    "bytes": 2481920,    "format": "jpeg"  },  "report_id": "FV-7K2M-9QXD-4T8R",  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",  "summary": {    "level": "L2",    "assessment": "authentic_untouched",    "action": "accept",    "ai": "very_low",    "edit": "none"  },  "result": {    "report": {      "schema": "fileverity.report/1",      "id": "FV-7K2M-9QXD-4T8R"    },    "stamped_at": 1793700130  },  "error": null,  "progress": null,  "usage": {    "amount": 199,    "currency": "usd",    "funding": "balance"  },  "metadata": {    "order_id": "A-10492"  },  "completed_at": 1793700131,  "expires_at": 1794304931}

إلغاء تحليل

POST https://api.fileverity.com/v1/analyses/{id}/cancel

يلغي تحليل مستند لا يزال قيد المعالجة ويحرّر المبلغ المحجوز له. لا يمكن إلغاء تحليلات الصور بعد إنشائها.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`id`	المسار	string	نعم	معرّف التحليل.
`Idempotency-Key`	الترويسة	string	لا	مفتاح فريد من 255 حرفًا كحد أقصى. يعيد تكرار الطلب بالمفتاح ومحتوى الطلب نفسيهما خلال 24 ساعة الاستجابة الأولى مع الترويسة idempotent-replayed: true؛ أما المفتاح نفسه مع محتوى طلب مختلف فيعيد 409.

الاستجابات

الحالة	الوصف	المحتوى
200	التحليل الملغى.	`Analysis`
400	طلب غير صالح. رموز الأخطاء: invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: not_found.	`Error`
409	تعارض مع الحالة الحالية. رموز الأخطاء: not_cancelable، idempotency_mismatch، idempotency_in_progress.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: Analysis

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"analysis"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`model`	string	نعم	النسخة المؤرَّخة التي أنتجت النتيجة.
`livemode`	boolean	نعم
`status`	إحدى القيم: `"processing"`، `"succeeded"`، `"failed"`، `"canceled"`	نعم
`file`	object	نعم
`report_id`	string أو null	نعم	رقم التقرير القابل للتحقق، FV-XXXX-XXXX-XXXX.
`report_url`	string أو null	نعم	صفحة التحقق العامة الخاصة بالتقرير.
`summary`	`ImageSummary` أو `DocumentSummary` أو null	نعم	الحكم المختصر الثابت: ImageSummary للصور، وDocumentSummary للمستندات، وnull إلى أن ينجح التحليل.
`result`	object أو null	نعم	يوجد ما إن تصبح قيمة status هي succeeded وإلى أن تنتهي صلاحية النتيجة.
`error`	object أو null	نعم
`progress`	object أو null	نعم
`usage`	object	نعم
`metadata`	object أو null	نعم
`completed_at`	integer أو null	نعم
`expires_at`	integer أو null	نعم	طابع زمني بصيغة Unix تُحذف النتيجة بعده.

حقول file

الحقل	النوع	مطلوب
`name`	string أو null	لا
`bytes`	integer أو null	لا
`format`	string أو null	لا

حقول result

الحقل	النوع	مطلوب	الوصف
`report`	`ImageReport` أو `DocumentReport`	لا	التقرير الكامل. قيمة report.schema هي fileverity.report/1 للصور وfileverity.docpro/1 للمستندات.
`stamped_at`	integer أو null	لا	طابع زمني بصيغة Unix للطابع الزمني الصادر للتقرير وفق RFC 3161، أو null.

حقول error

الحقل	النوع	مطلوب	الوصف
`code`	إحدى القيم: `"invalid_json"`، `"missing_parameter"`، `"invalid_parameter"`، `"text_too_short"`، `"text_too_long"`، `"unsupported_media_type"`، `"unsupported_language"`، `"file_not_found"`، `"unsupported_file"`، `"file_too_large"`، `"too_many_pixels"`، `"too_many_pages"`، `"document_too_long"`، `"invalid_file"`، `"password_required"`، `"wrong_password"`، `"not_examinable"`، `"missing_api_key"`، `"invalid_api_key"`، `"insufficient_balance"`، `"spend_limit_reached"`، `"not_found"`، `"model_not_found"`، `"not_cancelable"`، `"canceled"`، `"idempotency_mismatch"`، `"idempotency_in_progress"`، `"pending_files_limit"`، `"rate_limited"`، `"internal_error"`، `"analysis_failed"`، `"service_unavailable"`	لا
`message`	string	لا

حقول progress

الحقل	النوع	مطلوب	الوصف
`stage`	إحدى القيم: `"queued"`، `"reading"`، `"analyzing"`، `"reporting"`	لا
`done`	integer	لا	عدد الوحدات المنجزة في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`total`	integer	لا	عدد الوحدات في المرحلة الحالية عند معرفتها؛ وإلا فالقيمة 0.
`position`	integer	لا	الترتيب في قائمة الانتظار ما دامت المرحلة في الانتظار.

حقول usage

الحقل	النوع	مطلوب	الوصف
`amount`	integer	لا	الرسوم بالسنتات؛ 0 لفحوصات رصيد البدء المجاني ولحالات الفشل.
`currency`	`"usd"`	لا
`funding`	إحدى القيم: `"trial"`، `"balance"`، `null`	لا

رموز الأخطاء

الرمز	الحالة
`not_found`	404
`not_cancelable`	409
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvimg-2-2026-10-30",  "livemode": true,  "status": "canceled",  "file": {    "name": "claim-photo.jpg",    "bytes": 2481920,    "format": "jpeg"  },  "report_id": null,  "report_url": null,  "summary": null,  "result": null,  "error": {    "code": "canceled",    "message": "The analysis was canceled. You were not charged."  },  "progress": null,  "usage": {    "amount": 0,    "currency": "usd",    "funding": null  },  "metadata": null,  "completed_at": 1793700135,  "expires_at": null}

تنزيل تقرير PDF

GET https://api.fileverity.com/v1/analyses/{id}/report.pdf

يعيد تقرير PDF المختوم لتحليل ناجح ما دامت نتيجته محفوظة. وتحصل مفاتيح الاختبار على 404. وتتوفر أدلة المستند، مثل صور الصفحات، لمدة 3 ساعات بعد التحليل؛ وبعد ذلك يخلو ملف PDF منها، ويُشار إلى ذلك بالترويسة x-evidence-included: false.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`id`	المسار	string	نعم	معرّف التحليل.
`locale`	الاستعلام	إحدى القيم: `"en"`، `"fr"`، `"de"`، `"es"`، `"zh"`، `"vi"`، `"ar"`	لا	القيمة الافتراضية `"en"`.

الاستجابات

الحالة	الوصف	المحتوى
200	تقرير PDF.	ملف PDF
400	طلب غير صالح. رموز الأخطاء: invalid_parameter.	`Error`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: not_found.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

رموز الأخطاء

الرمز	الحالة
`invalid_parameter`	400
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf

النماذج

عرض قائمة النماذج

GET https://api.fileverity.com/v1/models

يعرض النماذج المتاحة لمفتاح API لديك.

الاستجابات

الحالة	الوصف	المحتوى
200	النماذج المتاحة.	`ModelList`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: ModelList

الحقل	النوع	مطلوب	الوصف
`object`	`"list"`	نعم
`data`	array من `Model`	نعم

حقول data

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"model"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix للنسخة المؤرَّخة الحالية.
`owned_by`	string	نعم
`name`	string	نعم
`type`	إحدى القيم: `"image"`، `"document"`، `"text"`	نعم
`description`	string	نعم
`snapshot`	string	نعم	النسخة المؤرَّخة التي يشير إليها المعرّف حاليًا.
`status`	إحدى القيم: `"available"`، `"preview"`، `"deprecated"`	نعم
`input`	object	نعم	المُدخل المقبول. بالنسبة إلى الملفات تُدرج الصيغ وحدود الحجم؛ وبالنسبة إلى النص تُدرج اللغات وحدود الطول.
`output`	object	نعم
`pricing`	object	نعم

حقول input

الحقل	النوع	مطلوب
`formats`	array من string	لا
`max_bytes`	integer	لا
`max_megapixels`	integer	لا
`max_pages`	integer	لا
`languages`	array من string	لا
`min_words`	integer	لا
`max_characters`	integer	لا

حقول output

الحقل	النوع	مطلوب	الوصف
`schema`	string	نعم	مخطط التقرير في نتائج التحليل.

حقول pricing

الحقل	النوع	مطلوب	الوصف
`currency`	`"usd"`	نعم
`unit`	string	نعم
`unit_amount`	integer	نعم	السعر لكل وحدة بالسنتات.

رموز الأخطاء

الرمز	الحالة
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/models \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "object": "list",  "data": [    {      "id": "fvimg-2",      "object": "model",      "created": 1793318400,      "owned_by": "fileverity",      "name": "FVIMG V2",      "type": "image",      "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",      "snapshot": "fvimg-2-2026-10-30",      "status": "available",      "input": {        "formats": [          "jpeg",          "png",          "webp"        ],        "max_bytes": 10485760,        "max_megapixels": 40      },      "output": {        "schema": "fileverity.report/1"      },      "pricing": {        "currency": "usd",        "unit": "image",        "unit_amount": 199      }    },    {      "id": "fvdoc-3",      "object": "model",      "created": 1793664000,      "owned_by": "fileverity",      "name": "FVDOC V3",      "type": "document",      "description": "Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.",      "snapshot": "fvdoc-3-2026-11-03",      "status": "available",      "input": {        "formats": [          "pdf",          "docx",          "doc",          "rtf",          "odt",          "pptx",          "txt"        ],        "max_bytes": 52428800,        "max_pages": 100      },      "output": {        "schema": "fileverity.docpro/1"      },      "pricing": {        "currency": "usd",        "unit": "document",        "unit_amount": 599      }    },    {      "id": "fvdoc-3-text",      "object": "model",      "created": 1793664000,      "owned_by": "fileverity",      "name": "FVDOC V3 Text",      "type": "text",      "description": "AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.",      "snapshot": "fvdoc-3-text-2026-11-03",      "status": "available",      "input": {        "languages": [          "en",          "fr",          "de",          "es",          "zh"        ],        "min_words": 100,        "max_characters": 100000      },      "output": {        "schema": "fileverity.text-detection/1"      },      "pricing": {        "currency": "usd",        "unit": "1000_characters",        "unit_amount": 14      }    }  ]}

جلب نموذج

GET https://api.fileverity.com/v1/models/{model}

يجلب نموذجًا بحسب معرّفه أو معرّف نسخته المؤرَّخة.

المعلمات

الاسم	الموضع	النوع	مطلوب	الوصف
`model`	المسار	string	نعم	معرّف النموذج أو معرّف النسخة المؤرَّخة.

الاستجابات

الحالة	الوصف	المحتوى
200	النموذج.	`Model`
401	مفتاح API مفقود أو غير صالح. رموز الأخطاء: missing_api_key، invalid_api_key.	`Error`
404	المورد غير موجود. رموز الأخطاء: model_not_found.	`Error`
429	عدد الطلبات كبير جدًا. رموز الأخطاء: rate_limited.	`Error`
500	خطأ داخلي؛ لا تُحتسب رسوم. رموز الأخطاء: internal_error.	`Error`

الاستجابة 200: Model

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم
`object`	`"model"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix للنسخة المؤرَّخة الحالية.
`owned_by`	string	نعم
`name`	string	نعم
`type`	إحدى القيم: `"image"`، `"document"`، `"text"`	نعم
`description`	string	نعم
`snapshot`	string	نعم	النسخة المؤرَّخة التي يشير إليها المعرّف حاليًا.
`status`	إحدى القيم: `"available"`، `"preview"`، `"deprecated"`	نعم
`input`	object	نعم	المُدخل المقبول. بالنسبة إلى الملفات تُدرج الصيغ وحدود الحجم؛ وبالنسبة إلى النص تُدرج اللغات وحدود الطول.
`output`	object	نعم
`pricing`	object	نعم

حقول input

الحقل	النوع	مطلوب
`formats`	array من string	لا
`max_bytes`	integer	لا
`max_megapixels`	integer	لا
`max_pages`	integer	لا
`languages`	array من string	لا
`min_words`	integer	لا
`max_characters`	integer	لا

حقول output

الحقل	النوع	مطلوب	الوصف
`schema`	string	نعم	مخطط التقرير في نتائج التحليل.

حقول pricing

الحقل	النوع	مطلوب	الوصف
`currency`	`"usd"`	نعم
`unit`	string	نعم
`unit_amount`	integer	نعم	السعر لكل وحدة بالسنتات.

رموز الأخطاء

الرمز	الحالة
`model_not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

مثال

curl https://api.fileverity.com/v1/models/fvimg-2 \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "fvimg-2",  "object": "model",  "created": 1793318400,  "owned_by": "fileverity",  "name": "FVIMG V2",  "type": "image",  "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",  "snapshot": "fvimg-2-2026-10-30",  "status": "available",  "input": {    "formats": [      "jpeg",      "png",      "webp"    ],    "max_bytes": 10485760,    "max_megapixels": 40  },  "output": {    "schema": "fileverity.report/1"  },  "pricing": {    "currency": "usd",    "unit": "image",    "unit_amount": 199  }}

أحداث Webhook

ترسل Fileverity هذه الأحداث إلى نقاط نهاية Webhook لديك. وتجد قواعد التحقق والتسليم في Webhooks.

الحدث analysis.completed

يُسلَّم إلى نقاط نهاية Webhook لديك وفق مواصفة Standard Webhooks: الترويسات webhook-id وwebhook-timestamp وwebhook-signature (v1,<base64 HMAC-SHA256 of id.timestamp.body>، ومفتاحه هو جزء base64 من المفتاح السري whsec_ الخاص بك). استجب بأي حالة 2xx خلال 10 ثوانٍ؛ وتُعاد محاولة التسليم الفاشل بفواصل زمنية تتزايد أسّيًا لمدة 3 أيام.

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم	يُرسل أيضًا في الترويسة webhook-id؛ استخدمه لتجاهل عمليات إعادة المحاولة المكررة.
`object`	`"event"`	نعم
`type`	إحدى القيم: `"analysis.completed"`، `"analysis.failed"`، `"balance.low"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`data`	`Analysis` أو `BalanceLow`	نعم	تحمل أحداث analysis.* الكائن نفسه الذي يعيده GET /analyses/{id}، على أن تكون قيمة result هي null دائمًا؛ اجلب النتيجة من نقطة النهاية تلك. وتحمل أحداث balance.low الرصيد والحد بالسنتات.

حقول data (BalanceLow)

الحقل	النوع	مطلوب	الوصف
`balance`	integer	نعم	الرصيد بالسنتات.
`threshold`	integer	نعم	حد التنبيه بالسنتات.

الحدث analysis.failed

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم	يُرسل أيضًا في الترويسة webhook-id؛ استخدمه لتجاهل عمليات إعادة المحاولة المكررة.
`object`	`"event"`	نعم
`type`	إحدى القيم: `"analysis.completed"`، `"analysis.failed"`، `"balance.low"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`data`	`Analysis` أو `BalanceLow`	نعم	تحمل أحداث analysis.* الكائن نفسه الذي يعيده GET /analyses/{id}، على أن تكون قيمة result هي null دائمًا؛ اجلب النتيجة من نقطة النهاية تلك. وتحمل أحداث balance.low الرصيد والحد بالسنتات.

الحدث balance.low

محتوى الطلب: application/json، مطلوب

الحقل	النوع	مطلوب	الوصف
`id`	string	نعم	يُرسل أيضًا في الترويسة webhook-id؛ استخدمه لتجاهل عمليات إعادة المحاولة المكررة.
`object`	`"event"`	نعم
`type`	إحدى القيم: `"analysis.completed"`، `"analysis.failed"`، `"balance.low"`	نعم
`created`	integer	نعم	طابع زمني بصيغة Unix.
`data`	`Analysis` أو `BalanceLow`	نعم	تحمل أحداث analysis.* الكائن نفسه الذي يعيده GET /analyses/{id}، على أن تكون قيمة result هي null دائمًا؛ اجلب النتيجة من نقطة النهاية تلك. وتحمل أحداث balance.low الرصيد والحد بالسنتات.

curl https://api.fileverity.com/v1/openapi.json