# مرجع API

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

المصدر: https://fileverity.com/ar/docs/api-reference

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

## الاصطلاحات

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

## كشف النصوص

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

`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**

```bash
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)"
```

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

```bash
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"}'
```

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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**

```bash
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**

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

**الاستجابة**

```json
{
  "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**

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

**الاستجابة**

```json
{
  "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](https://fileverity.com/ar/docs/webhooks.md).

### الحدث 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

يُسلَّم إلى نقاط نهاية 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 الرصيد والحد بالسنتات. |

### الحدث balance.low

يُسلَّم إلى نقاط نهاية 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 الرصيد والحد بالسنتات. |

**OpenAPI**

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