# كشف الصور

> اكشف ما إذا كانت الصورة كلها مولَّدة بالذكاء الاصطناعي عبر POST /images/detections. استدعاء متزامن واحد: حقول الطلب والاستجابة، وقيم الإجابة، والحدود، والفوترة.

المصدر: https://fileverity.com/ar/docs/image-detections

يُجري `POST /images/detections` كشف الصور المولَّدة بالذكاء الاصطناعي. يخبرك ما إذا كانت الصورة كلها مولَّدة بالذكاء الاصطناعي بالنموذج `vereye-2-detect`، اعتمادًا على النماذج وبيانات Content Credentials ووسوم الذكاء الاصطناعي والعلامات المائية نفسها المعتمدة في تقرير التحقق من الصورة (`vereye-2`)، ولذلك يعطيان الإجابة نفسها عن التوليد بالذكاء الاصطناعي. وهو متزامن: النتيجة في الاستجابة نفسها.

لا يفحص التعديلات الموضعية، ومنها تعديلات الذكاء الاصطناعي على جزء من الصورة، ولا يعيد رقم تقرير ولا ملف PDF. وللتعديلات والمنشأ وسجل يمكن لأي شخص التحقق منه، أنشئ [تحليلًا](https://fileverity.com/ar/docs/analyses.md) بالنموذج `vereye-2`.

**الطلب: cURL**

```bash
curl https://api.fileverity.com/v1/images/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \
  -F file=@photo.jpg
```

**الطلب: JavaScript**

```javascript
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");

const response = await fetch("https://api.fileverity.com/v1/images/detections", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() },
  body: form,
});
const detection = await response.json();
console.log(detection.verdict, detection.ai);
```

**الطلب: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/images/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    files={"file": open("photo.jpg", "rb")},
)
detection = response.json()
print(detection["verdict"], detection["ai"])
```

## محتوى الطلب

أرسل الصورة بصيغة `multipart/form-data` في الحقل `file`، بحجم لا يتجاوز 4 ميغابايت. وللصور الأكبر، حتى 10 ميغابايت، ارفعها أولًا عبر [`POST /files`](https://fileverity.com/ar/docs/files.md) ثم أرسل JSON بدلًا من ذلك:

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `file` | file أو string | نعم | الصورة في طلب multipart، أو معرّف صورة مرفوعة في طلب JSON. الصيغ JPEG وPNG وWEBP، حتى 40 ميغابكسل. يُستهلك معرّف الملف بهذا الفحص. |
| `model` | string | لا | الافتراضي `vereye-2-detect`. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة `vereye-2-detect-2026-10-30`. |

تُرفض الحقول غير المعروفة برمز الخطأ `invalid_parameter`.

## الاستجابة

**200 OK**

```json
{
  "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "image.detection",
  "created": 1794096000,
  "model": "vereye-2-detect-2026-10-30",
  "livemode": true,
  "verdict": "ai_generated",
  "ai": {
    "key": "very_likely",
    "basis": "detected",
    "strength": "strong",
    "likelihood": 100
  },
  "generator": null,
  "signals": [
    {
      "id": "model_1",
      "state": "ai"
    },
    {
      "id": "model_2",
      "state": "ai"
    },
    {
      "id": "credentials",
      "state": "none"
    },
    {
      "id": "watermark",
      "state": "none"
    },
    {
      "id": "label",
      "state": "none"
    },
    {
      "id": "tool_data",
      "state": "none"
    },
    {
      "id": "camera",
      "state": "none"
    }
  ],
  "regions": [
    {
      "x": 0,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 0,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 2
    },
    {
      "x": 0,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 512,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    }
  ],
  "candidates": [
    {
      "name": "Midjourney",
      "score": 0.65
    },
    {
      "name": "OpenAI",
      "score": 0.25
    }
  ],
  "quality": {
    "overall": "fair",
    "resolution": "good",
    "compression": "fair",
    "metadata": "fair",
    "distribution": "good"
  },
  "limits": [
    "no_metadata"
  ],
  "image": {
    "width": 1536,
    "height": 1024,
    "format": "jpeg",
    "jpeg_quality": 85
  },
  "usage": {
    "credits": 4
  }
}
```

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `id` | string | معرّف الكشف، ويبدأ بالبادئة `idet_`. |
| `object` | string | دائمًا `image.detection`. |
| `created` | integer | طابع زمني بصيغة Unix. |
| `model` | string | النسخة المؤرَّخة التي أنتجت النتيجة. |
| `livemode` | boolean | `false` لمفاتيح الاختبار. |
| `verdict` | string | `ai_generated`: الصورة مولَّدة بالذكاء الاصطناعي. `no_ai_signs`: لا شيء يشير إلى التوليد بالذكاء الاصطناعي. `inconclusive`: الأدلة لا تحسم. |
| `ai` | object | الإجابة عن التوليد بالذكاء الاصطناعي، بالقيم نفسها الواردة في `questions.ai` في [تقرير الصورة](https://fileverity.com/ar/docs/analyses.md#report-image). |
| `generator` | object أو null | أداة التوليد التي يصرّح بها الملف عبر Content Credentials أو البيانات الوصفية أو العلامة المائية، مع `name` و`basis`. تكون `null` حين لا يسمّي الملف أداة. |
| `signals` | array | الفحوصات التي تستند إليها الإجابة، ولكل منها `id` و`state`. راجع [الإشارات](#signals). |
| `regions` | array أو null | شبكة تقسّم الصورة إلى خلايا واسعة. لكل خلية `x` و`y` و`w` و`h` بالبكسل بحسب الصورة المعروضة، و`level` من 0 إلى 3 يدل على قوة سمات التوليد. وتكون القيمة `null` حين تكون الصورة أصغر من أن تُقسَّم إلى شبكة. |
| `candidates` | array | حتى ثلاث عائلات من المولِّدات تتشابه سمات بكسلاتها مع الصورة أكثر من غيرها، ولكل منها `name` و`score` من 0 إلى 1. وتكون فارغة ما لم يكن الحكم `ai_generated`. |
| `quality` | object أو null | مدى صلاحية الملف للتحليل: `overall` و`resolution` و`compression` و`metadata` و`distribution`، وقيمة كل منها `good` أو `fair` أو `poor`. |
| `limits` | array | ما يحدّ من النتيجة: `low_resolution` أو `heavy_compression` أو `platform_copy` أو `no_metadata` أو `models_disagree`. |
| `image` | object | `width` و`height` بحسب الصورة المعروضة، و`format`، و`jpeg_quality` وهي جودة JPEG المقدَّرة أو `null`. |
| `usage` | object | `credits` المخصومة. |

## قراءة الإجابة

| `ai.key` | `verdict` | المعنى |
| --- | --- | --- |
| `labelled` | `ai_generated` | تصرّح Content Credentials أو وسم للذكاء الاصطناعي أو علامة مائية بالتوليد بالذكاء الاصطناعي. تكون `ai.basis` بقيمة `verified` للبيانات الموثوقة، وإلا فهي `declared` أو `detected`. |
| `very_likely`, `suspected` | `ai_generated` | تشير البكسلات إلى التوليد بالذكاء الاصطناعي، بقوة أو مع بعض التعارض. |
| `undecided` | `inconclusive` | الإشارات ضعيفة أو متعارضة. |
| `low`, `very_low` | `no_ai_signs` | لا شيء في البكسلات أو البيانات الوصفية يشير إلى التوليد بالذكاء الاصطناعي. |

تكون `ai.strength` إحدى القيم `strong` أو `moderate` أو `limited`، وتبيّن مدى قوة دعم الأدلة للإجابة. وتتراوح `ai.likelihood` من 0 إلى 100 بخطوات من 5، وتكون `null` في حالة `labelled`.

> **ملاحظة.** لا تدل `no_ai_signs` على أن الصورة أصلية أو غير معدَّلة. فكشف الصور المولَّدة بالذكاء الاصطناعي لا يبحث عن التعديلات. وحين يتوقف قرار عليها، شغّل تقرير التحقق من الصورة واجعل شخصًا يراجع النتيجة.

## الإشارات

يسرد `signals` كل فحص أُجري، لتعرف ما تستند إليه الإجابة. وتشير القيمة `ai` في `state` إلى التوليد بالذكاء الاصطناعي.

| `id` | `state` | الفحص |
| --- | --- | --- |
| `model_1`, `model_2` | `ai`, `unclear`, `clear`, `unavailable` | نموذجان دُرِّبا بصورة مستقلة يحلّلان البكسلات. |
| `credentials` | `ai`, `ai_unverified`, `other`, `none` | Content Credentials (C2PA). `ai_unverified`: تُقرّ الـ Content Credentials بالتوليد بالذكاء الاصطناعي لكن تعذّر التحقق من جهة إصدارها. `other`: الـ Content Credentials موجودة ولا تُقرّ بالتوليد بالذكاء الاصطناعي. |
| `watermark` | `ai`, `none`, `unavailable` | علامات مائية غير مرئية تضمّنها أدوات التوليد مفتوحة المصدر في البكسلات. |
| `label` | `ai`, `none` | إقرار بالتوليد بالذكاء الاصطناعي في البيانات الوصفية، مثل نوع المصدر الرقمي في IPTC. |
| `tool_data` | `ai`, `none` | أوامر نصية أو معاملات أو أسماء مولِّدات محفوظة في الملف. |
| `camera` | `present`, `none` | الشركة المصنِّعة للكاميرا وطرازها وبيانات التعريض. يمكن تعديلها، ولا تتحقق منها نقطة النهاية هذه. |

يبيّن `regions` مواضع اشتداد سمات التوليد. وتحمل الخلايا ذات المستوى 3 سمات قوية. وحين يكون الحكم `no_ai_signs` وتبلغ بعض الخلايا المستوى 3، فقد يكون جزء من الصورة مولَّدًا أو معدَّلًا بالذكاء الاصطناعي: فنقطة النهاية هذه لا تفحص التعديلات الموضعية، لذا شغّل تقرير التحقق من الصورة.

> **ملاحظة.** `candidates` مؤشر وليس تحديدًا للمولِّد. فهو يرتّب عائلات المولِّدات بحسب مدى تشابه سمات البكسلات معها، ويظهر أي مولِّد خارج مجموعة المرجع بوصفه أقرب مطابقة له. اعتمد على `generator` حين يذكر الملف نفسه اسم الأداة.

## الفوترة

- يستهلك كشف الصور المولَّدة بالذكاء الاصطناعي 4 وحدات رصيد لكل صورة.
- يستهلك تقرير التحقق من الصورة نفسها في مساحة العمل نفسها خلال 7 أيام 36 وحدة رصيد بدلًا من 40: فوحدات الكشف تُحتسب منه مرة واحدة. ويُبلغ التحليل عن الرسم في `usage.credits`.
- لا تُحتسب رسوم على الطلبات المرفوضة قبل التقييم: المعاملات غير الصالحة، والملفات غير المدعومة أو التالفة، وتجاوز حدود الحجم وما شابهها. أما الفحص الذي يفشل داخل الخدمة (`service_unavailable` و`analysis_failed`) فيُفرَج عن وحداته ولا يُحتسب.
- عند عدم كفاية وحدات رصيد يُرجع الطلب `insufficient_balance` (402).

## ما الذي يُخزَّن

تُفحص الصورة ثم تُحذف. تحتفظ Fileverity بالنتيجة دون الصورة (الحكم والإجابة والمولِّد والإشارات والمناطق والمرشّحات والجودة والأبعاد وبصمة SHA-256 للملف والاستخدام) مدة 7 أيام، حتى تعرضها لوحة التحكم ويمكن احتساب الاستخدام وتدقيقه. ويحصل الطلب المُعاد الذي يحمل `Idempotency-Key` نفسه على النتيجة المحفوظة خلال 24 ساعة. عمليات كشف الصور متزامنة: فلا تظهر في `GET /analyses` ولا تُرسل أحداث Webhook. ولا تسجّل مفاتيح الاختبار شيئًا. راجع [الاحتفاظ بالبيانات والأمان](https://fileverity.com/ar/docs/security.md).

## الأخطاء

| الرمز | الحالة | السبب |
| --- | --- | --- |
| `missing_parameter` | 400 | الحقل `file` مفقود. |
| `invalid_parameter` | 400 | نوع أحد الحقول خاطئ، أو أُرسل حقل غير معروف، أو النموذج ليس نموذج كشف صور، أو `Idempotency-Key` غير صالح. |
| `file_not_found` | 400 | معرّف الملف غير معروف أو منتهي الصلاحية أو سبق استخدامه. |
| `unsupported_file`, `invalid_file` | 415, 422 | الملف ليس صورة JPEG أو PNG أو WebP، أو أنه تالف. |
| `file_too_large`, `too_many_pixels` | 413 | يتجاوز ملف multipart حجم 4 ميغابايت، أو يتجاوز الملف المرفوع 10 ميغابايت، أو تتجاوز الصورة 40 ميغابكسل. |
| `unsupported_media_type`, `invalid_json` | 415, 400 | المحتوى ليس `multipart/form-data` ولا كائن JSON. |
| `model_not_found` | 404 | قيمة `model` غير معروفة. |
| `insufficient_balance`, `spend_limit_reached` | 402 | لا يكفي الرصيد أو الحد الشهري للمفتاح لتغطية الطلب. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | استُخدم `Idempotency-Key` مع محتوى طلب مختلف، أو لا يزال طلبه الأول قيد التنفيذ. |
| `service_unavailable`, `analysis_failed` | 503, 502 | خدمة الكشف غير متاحة مؤقتًا أو مشغولة. لا تُحتسب رسوم؛ أعد المحاولة. يحمل `service_unavailable` ترويسة `retry-after`. |

> **ملاحظة.** أرسل `Idempotency-Key` حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع [منع التكرار](https://fileverity.com/ar/docs/idempotency.md).

