> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderation API

> افحص المطالبات والصور قبل أن ينشئ منتجك القائم على الذكاء الاصطناعي المحتوى، واحصل على حكم بالسماح أو الإبلاغ أو الرفض مع درجة لـ 17 فئة من المحتوى.

<CardGroup cols={2}>
  <Card title="Screen a Prompt" icon="shield-check" href="/api-reference/moderation/screen">
    أرسل نصًا أو صورة أو كليهما، واحصل على حكم.
  </Card>

  <Card title="Get Moderation Usage" icon="chart-column" href="/api-reference/moderation/get-usage">
    اطّلع على عمليات الفحص القابلة للفوترة ورسومك التالية.
  </Card>
</CardGroup>

## نظرة عامة

يفحص Moderation API مدخلات المستخدم قبل أن ينشئ منتجك القائم على الذكاء الاصطناعي محتوىً منها. ترسل نص مطالبة أو صورة أو كليهما، ويعيد Dodo Payments حكمًا هو `allow` أو `flag` أو `deny`، إلى جانب درجة لكل فئة من فئات المحتوى.

استخدمه أمام أي نموذج لإنشاء الصور أو الفيديو أو النصوص يتلقى مدخلات من المستخدمين. يكون Moderation API مفعّلًا لكل نشاط تجاري افتراضيًا ويعمل باستخدام مفتاح Dodo Payments API الحالي لديك، لذلك لا تحتاج إلى التسجيل في خدمة إضافية. يمكن لـ Dodo Payments إيقافه لنشاط تجاري محدد، وعندها تعيد الاستدعاءات `403` مع `MODERATION_DISABLED`.

## لماذا أنشأنا Moderation API

ينشئ منتج الذكاء الاصطناعي محتوى جديدًا من أي شيء يكتبه المستخدمون. لا يمكنك مراجعة كل مطالبة يدويًا، وقد يعرّض ناتج ضار واحد نشاطك التجاري للخطر.

بصفتها Merchant of Record، تتحمل Dodo Payments المسؤولية القانونية والسمعية عما يُباع عبر المنصة. تراجع [Merchant Acceptance Policy](/miscellaneous/merchant-acceptance) أدوات إنشاء المحتوى بالذكاء الاصطناعي ولا تسمح بانتحال الشخصية أو التزييف العميق أو المحتوى الصريح، بما في ذلك المحتوى المُنشأ بالذكاء الاصطناعي. قد يُوضع الحساب الذي ينشئ محتوى ضارًا أو يتسبب في عمليات رد مبالغ مفرطة أو إشعارات من شركاء الدفع قيد المراجعة أو يُعلّق.

أنشأنا Moderation API حتى تتمكن من إيقاف هذا المحتوى قبل أن ينشئه نموذجك:

* **افحص قبل الإنشاء.** لا تصل المطالبة المحظورة إلى نموذجك، لذلك لا يوجد ناتج ضار ولا تنفق موارد حوسبة عليه.
* **غطِّ الفئات المهمة للإنشاء.** يسجل الفحص درجات لـ 17 فئة، بما في ذلك شبه الشخص الحقيقي، والصور الحميمة غير التوافقية، واللغة التي تشير إلى أن الشخص قاصر، والجمع بين شخص حقيقي ومحتوى جنسي الذي يحدد التزييف العميق الجنسي.
* **تكامل بلا مورّد آخر.** تعمل API باستخدام مفتاح Dodo Payments API، وتُخصم رسومها من رصيدك. لا يوجد عقد أو فاتورة أو حساب منفصل.
* **حافظ على خصوصية محتوى المستخدمين.** لا تخزّن Dodo Payments النصوص والصور التي تفحصها ولا تسجلها.

<Note>
  Moderation API أداة لتطبيق سياساتك أنت. لا يحل محل Merchant Acceptance Policy، وتظل مسؤولًا عن المحتوى الذي ينشئه منتجك.
</Note>

## آلية العمل

استدعِ Moderation API من الواجهة الخلفية بعد أن يرسل المستخدم مطالبة وقبل تشغيل نموذجك:

```mermaid theme={null}
flowchart LR
  A[User submits a prompt] --> B[Your backend calls POST /moderation/screen]
  B -->|allow| C[Generate]
  B -->|flag| D[Apply your own policy]
  B -->|deny| E[Block the request]
  B -->|error, no verdict| E
```

كل استدعاء هو **فحص** واحد. ويُحتسب النص والصورة المرسلان في الاستدعاء نفسه فحصًا واحدًا.

### الأحكام

يحمل الحقل `decision` الحكم:

| الحكم   | المعنى                                                        | الإجراء                                                             |
| ------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
| `allow` | اجتاز المحتوى الفحص.                                          | أنشئ المحتوى.                                                       |
| `flag`  | تجاوز المحتوى حدًا لفئة تستدعي التقييم. وهذا ليس رفضًا لينًا. | طبّق سياستك الخاصة. يمكنك الحظر أو الإرسال إلى المراجعة أو الإنشاء. |
| `deny`  | يجب عدم إنشاء المحتوى.                                        | احظر الطلب واعرض للمستخدم خطأً.                                     |

<Warning>
  لا تنشئ المحتوى عند عدم تلقي أي حكم. يعني `503` أن Dodo Payments لم تتمكن من إصدار حكم، كما أن انتهاء المهلة أو خطأ الشبكة يتركانك من دونه. تعامل مع جميع هذه الحالات باعتبارها حظرًا واطلب من المستخدم المحاولة مرة أخرى.
</Warning>

## فحص مطالبة

لفحص مطالبة، أرسل طلب `POST` إلى `/moderation/screen` مع واحد على الأقل من `text` و`image`. يقبل الطلب ثلاثة حقول:

| الحقل        | النوع  | الوصف                                                                                                                |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `text`       | string | النص المطلوب فحصه، بحد أقصى 8,000 حرف.                                                                               |
| `image`      | string | الصورة المطلوب فحصها بصيغة base64، مع بادئة `data:image/...;base64,` أو بدونها.                                      |
| `request_id` | string | اختياري. المعرّف الذي تحدده لهذا الفحص، مثل معرّف إنشاء، بحد أقصى 128 حرفًا ومن دون أحرف تحكم. يعيده الرد دون تغيير. |

تعرِض حِزمتا TypeScript وPython SDK نقطة النهاية باسم `client.moderation.screen()`. يحظر هذا المثال الإنشاء عند `deny` أو `flag` أو أي خطأ:

<Note>
  تستدعي الأمثلة الوضع المباشر، لأن الوضع المباشر فقط يشغّل نموذج الإشراف. يعيد وضع الاختبار [أحكامًا وهمية](#testing-your-integration) ولا يفحص المحتوى مطلقًا. وتتم فوترة الفحوص في الوضع المباشر.
</Note>

<CodeGroup>
  ```typescript Node.js expandable theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
  });

  async function generateImage(prompt: string, generationId: string) {
    let verdict;
    try {
      verdict = await client.moderation.screen({
        text: prompt,
        request_id: generationId,
      });
    } catch (err) {
      // No verdict: do not generate.
      throw new Error('Moderation is unavailable. Try again in a moment.');
    }

    if (verdict.decision !== 'allow') {
      throw new Error('This prompt cannot be generated. Revise it and try again.');
    }

    return myModel.generate(prompt);
  }
  ```

  ```python Python expandable theme={null}
  import os
  from dodopayments import DodoPayments, APIError

  client = DodoPayments(
      bearer_token=os.environ["DODO_PAYMENTS_API_KEY"],
      environment="live_mode",
  )

  def generate_image(prompt: str, generation_id: str):
      try:
          verdict = client.moderation.screen(text=prompt, request_id=generation_id)
      except APIError:
          # No verdict: do not generate.
          raise RuntimeError("Moderation is unavailable. Try again in a moment.")

      if verdict.decision != "allow":
          raise ValueError("This prompt cannot be generated. Revise it and try again.")

      return my_model.generate(prompt)
  ```

  ```bash cURL theme={null}
  curl -X POST https://live.dodopayments.com/moderation/screen \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "a watercolor painting of a lighthouse at sunset",
      "request_id": "gen_7Hc2k9"
    }'
  ```
</CodeGroup>

يتعامل المثال مع `flag` مثل `deny`. إذا كان منتجك يسمح ببعض المحتوى المُبلّغ عنه، فتحقق من `triggered` لاتخاذ القرار حسب الفئة بدلًا من ذلك.

<Tip>
  افحص النص الذي كتبه المستخدم، لا قالب المطالبة الذي تضعه حوله. قالبك الخاص نفسه في كل استدعاء ولا يضيف شيئًا إلى الفحص.
</Tip>

### فحص الصور

أرسل صورة لفحص صورة مرجعية مرفوعة أو صورة منشأة قبل عرضها. يجب أن تستوفي الصورة المتطلبات التالية:

* التنسيق هو JPEG أو PNG أو WebP أو GIF أو BMP.
* لا تتجاوز سلسلة base64 عدد 6,991,530 حرفًا، ولا تتجاوز الصورة بعد فك ترميزها 5 MiB.
* الصورة إطار ثابت واحد. تُرفض صور GIF وWebP المتحركة.
* يبلغ طول الحافة الأطول 32 بكسل على الأقل.

تعيد الصورة التي تفشل في أحد هذه الاختبارات `400` مع `MODERATION_INVALID_IMAGE`، أو `413` مع `MODERATION_INPUT_TOO_LARGE` عندما تكون كبيرة جدًا.

لفحص صورة، اقرأ الملف، وحوّله إلى base64، وأرسله في `image`. لفحص صورة ومطالبتها معًا، أرسل كليهما `text` و`image` في الاستدعاء نفسه. ويُحتسب ذلك فحصًا واحدًا. يستخدم هذا المثال `client` من المثال السابق:

<CodeGroup>
  ```typescript Node.js expandable theme={null}
  import { readFile } from 'node:fs/promises';

  async function screenImage(path: string, prompt: string, generationId: string) {
    const image = (await readFile(path)).toString('base64');

    const verdict = await client.moderation.screen({
      image, // or `data:image/png;base64,${image}`
      text: prompt, // optional: screen the prompt with the image
      request_id: generationId,
    });

    return verdict.decision === 'allow';
  }
  ```

  ```python Python expandable theme={null}
  import base64

  def screen_image(path: str, prompt: str, generation_id: str) -> bool:
      with open(path, "rb") as f:
          image = base64.b64encode(f.read()).decode("ascii")

      verdict = client.moderation.screen(
          image=image,  # or f"data:image/png;base64,{image}"
          text=prompt,  # optional: screen the prompt with the image
          request_id=generation_id,
      )
      return verdict.decision == "allow"
  ```

  ```bash cURL expandable theme={null}
  # Builds the JSON body with jq, so a large image does not hit the shell argument limit.
  base64 < reference.png | tr -d '\n' \
    | jq -Rs '{image: ., text: "turn this photo into a watercolor painting", request_id: "gen_7Hc2k9"}' \
    | curl -X POST https://live.dodopayments.com/moderation/screen \
        -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
        -H "Content-Type: application/json" \
        --data @-
  ```
</CodeGroup>

تعامل مع أخطاء فحص الصورة بالطريقة نفسها التي تتعامل بها مع فحص النص: إذا فشل الاستدعاء، فلا تنشئ المحتوى.

## قراءة الرد

يعيد الرد الحكم والأدلة التي يستند إليها:

| الحقل                | الوصف                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `decision`           | الحكم: `allow` أو `flag` أو `deny`.                                                                              |
| `triggered`          | الفئات التي تجاوزت درجاتها الحد الخاص بالفئة. وقد يكون فارغًا في حالة `flag` الناتج عن الفحص العام.              |
| `compound_triggered` | `true` عندما يتجاوز شبه الشخص الحقيقي والمحتوى الجنسي معًا حدهما المشترك، وهو نمط التزييف العميق الجنسي.         |
| `categories`         | احتمال، من 0 إلى 1، لوقوع المحتوى ضمن كل فئة.                                                                    |
| `provenance`         | كيفية قياس كل درجة: `targeted` بواسطة فحص لتلك الفئة وحدها، أو `broad` بواسطة الفحص العام الذي يغطي جميع الفئات. |
| `notes`              | أسباب القرار بصياغة مفهومة للبشر. قد تتغير الصياغة، لذا لا تحللها برمجيًا.                                       |
| `normalized_applied` | `true` عندما فُحص النص أيضًا بعد إزالة التعتيم، مثل الأحرف غير المرئية أو المتشابهة.                             |
| `passes`             | عدد أسئلة نعم/لا التي أجاب عنها النموذج لهذا الفحص.                                                              |
| `latency_ms`         | مدة الفحص بالمللي ثانية.                                                                                         |
| `request_id`         | `request_id` الذي أرسلته، أو `null`.                                                                             |

ابنِ منطقك على `decision` و`triggered`. لكل فئة حد خاص بها، لذا لا يتوافق حد درجات واحد في شفرتك مع الحكم.

### الفئات

يسجل كل رد درجات المحتوى مقابل 17 فئة:

| الفئة                             | تشمل                                                                  |
| --------------------------------- | --------------------------------------------------------------------- |
| `violent_crimes`                  | الجرائم العنيفة.                                                      |
| `sex_related_crimes`              | الجرائم المرتبطة بالجنس.                                              |
| `child_sexual_exploitation`       | الاستغلال الجنسي للأطفال.                                             |
| `suicide_and_self_harm`           | الانتحار وإيذاء النفس.                                                |
| `indiscriminate_weapons`          | الأسلحة الكيميائية أو البيولوجية أو الإشعاعية أو النووية أو المتفجرة. |
| `intellectual_property`           | انتهاك حقوق الطبع والنشر أو العلامات التجارية.                        |
| `defamation`                      | تصوير زائف يُرجح أن يضر بسمعة شخص حقيقي.                              |
| `non_violent_crimes`              | الجرائم غير العنيفة.                                                  |
| `hate`                            | الحط من قدر الأشخاص بسبب سمة محمية.                                   |
| `privacy`                         | معلومات خاصة حساسة عن شخص.                                            |
| `specialized_advice`              | نصائح مالية أو طبية أو قانونية أو انتخابية غير مؤهلة.                 |
| `sexual_content`                  | محتوى جنسي صريح أو إباحي.                                             |
| `non_consensual_intimate_imagery` | تعرية شخص حقيقي أو إزالة ملابسه أو إضفاء طابع جنسي عليه.              |
| `minor_coded_language`            | لغة تشير إلى أن الشخص قاصر.                                           |
| `real_person_likeness`            | شبه شخص حقيقي محدد الهوية ومُسمّى.                                    |
| `living_artist_style`             | تقليد الأسلوب المميز لفنان حي محدد.                                   |
| `prompt_injection`                | محاولة تجاوز تعليمات النظام أو التلاعب بها.                           |

## معالجة الأخطاء

تعيد الأخطاء نص خطأ Dodo Payments القياسي مع `code` و`message`. لا يُعد أي خطأ حكمًا، ولذلك لا يسمح أي منها بالإنشاء:

| الحالة | `code`                       | السبب                                                      | الإجراء                                                            |
| ------ | ---------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| `400`  | `INVALID_REQUEST_PARAMETERS` | الطلب غير صالح، أو لا يحتوي على `text` ولا `image`.        | أصلح الطلب.                                                        |
| `400`  | `MODERATION_INVALID_IMAGE`   | يتعذر فك ترميز الصورة، أو أنها متحركة، أو صغيرة جدًا.      | أرسل صورة ثابتة مدعومة.                                            |
| `403`  | `MODERATION_DISABLED`        | أوقفت Dodo Payments Moderation API لنشاطك التجاري.         | اتصل بالدعم لمعرفة السبب.                                          |
| `413`  | `MODERATION_INPUT_TOO_LARGE` | يتجاوز `text` عدد 8,000 حرف، أو يتجاوز `image` حد الحجم.   | قصّر النص أو صغّر الصورة.                                          |
| `429`  | `MODERATION_OVERLOADED`      | بلغت خدمة الإشراف سعتها. هذا حد لمعدل المعالجة وليس حكمًا. | انتظر عدد الثواني الوارد في ترويسة `Retry-After`، ثم أعد المحاولة. |
| `503`  | `MODERATION_UNAVAILABLE`     | لا يتوفر أي حكم.                                           | لا تنشئ المحتوى. أعد المحاولة لاحقًا.                              |

تعيد SDKs المحاولة مرتين افتراضيًا عند `429` أو `503`، وتنتظر `Retry-After` بين المحاولات. عند نفاد المحاولات، ترفع SDK خطأً، ويجب أن تحظر شفرتك الطلب.

## اختبار تكاملك

يعيد وضع الاختبار أحكامًا وهمية ولا يستدعي نموذج الإشراف مطلقًا، حتى تتمكن من اختبار التوجيه دون تكلفة. أرسل الطلبات إلى `https://test.dodopayments.com` باستخدام مفتاح API لوضع الاختبار.

الحكم الوهمي الافتراضي هو `allow`. للحصول على نتيجة أخرى، ضع إحدى السلاسل التالية في أي موضع من `text`:

| السلسلة في `text`      | الرد                                              |
| ---------------------- | ------------------------------------------------- |
| `dodo_mock_flag`       | `200` مع ضبط `decision` على `flag`                |
| `dodo_mock_deny`       | `200` مع ضبط `decision` على `deny`                |
| `dodo_mock_overloaded` | `429` `MODERATION_OVERLOADED` مع `Retry-After: 1` |
| `dodo_mock_not_ready`  | `503` `MODERATION_UNAVAILABLE`                    |

يحمل الحكم الوهمي ملاحظة تفيد بأنه وهمي، وتكون جميع درجات فئاته `0`. يطبق وضع الاختبار عملية التحقق نفسها الخاصة بالطلبات كما في الوضع المباشر. وبالنسبة إلى الصور، يتحقق من ترميز base64 والتنسيق، لكنه لا يتحقق من عدد الإطارات أو الأبعاد.

قبل الانتقال إلى الوضع المباشر، تأكد من أن تكاملك يتعامل مع كل حالة:

<Steps>
  <Step title="Deny Blocks Generation">
    أرسل `dodo_mock_deny` وتأكد من عدم استدعاء نموذجك.
  </Step>

  <Step title="Flag Follows Your Policy">
    أرسل `dodo_mock_flag` وتأكد من أن منتجك ينفذ ما تنص عليه سياستك.
  </Step>

  <Step title="Overload Retries">
    أرسل `dodo_mock_overloaded` وتأكد من أن شفرتك تنتظر `Retry-After` ولا تنشئ المحتوى دون حكم.
  </Step>

  <Step title="An Outage Blocks Generation">
    أرسل `dodo_mock_not_ready` وتأكد من عدم استدعاء نموذجك.
  </Step>

  <Step title="Every Generation Path Screens">
    تحقق من أن كل مسار في الشفرة يصل إلى نموذجك يستدعي Moderation API أولًا.
  </Step>
</Steps>

## التسعير والفوترة

تبلغ تكلفة Moderation API **0.30 دولار أمريكي لكل 1,000 فحص قابل للفوترة**. لا توجد فئة مجانية ولا حد أدنى.

الفحص القابل للفوترة هو فحص في الوضع المباشر يعيد حكمًا. وتكون الفحوص التالية مجانية ولا تُحتسب:

* الفحوص في وضع الاختبار.
* الفحوص التي تعيد خطأً، بما في ذلك `429` و`503`.

تُصدر Dodo Payments فواتير عن كتل كاملة من 1,000 فحص. تُحتسب رسوم كل كتلة كاملة خلال ساعة واحدة، بينما تظل الفحوص التي لا تكمل كتلة غير مفوترة حتى تكملها. تُخصم الرسوم من رصيدك بالدولار الأمريكي وتظهر في [سجل الرصيد](/api-reference/balance-ledger/list-ledger-entries) مع نوع الحدث `moderation_fees`. وتظهر في الدفعات تحت **رسوم الإشراف**.

### تتبع الاستخدام

لعرض استخدامك، استدعِ `GET /moderation/usage`. يعيد الرد:

| الحقل                   | الوصف                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `unbilled_screens`      | الفحوص القابلة للفوترة التي لم تفرض Dodo Payments رسومها بعد.                           |
| `screens_to_next_block` | الفحوص القابلة للفوترة المطلوبة لإكمال الكتلة التالية من 1,000.                         |
| `daily`                 | فحوصك القابلة للفوترة لكل يوم UTC خلال آخر 30 يومًا. تُحذف الأيام التي لا تتضمن فحوصًا. |

<CodeGroup>
  ```bash cURL theme={null}
  curl https://live.dodopayments.com/moderation/usage \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
  ```

  ```typescript Node.js theme={null}
  const usage = await client.moderation.retrieveUsage();
  console.log(usage.unbilled_screens, usage.screens_to_next_block);
  ```

  ```python Python theme={null}
  usage = client.moderation.retrieve_usage()
  print(usage.unbilled_screens, usage.screens_to_next_block)
  ```
</CodeGroup>

لا يسجل وضع الاختبار أي فحوص، لذلك لا تعرض نقطة نهاية الاستخدام أي نشاط لوضع الاختبار.

## الوصول والخصوصية

يتطلب الفحص مفتاح API يتمتع بوصول للكتابة. ويمكن لأي مفتاح API، بما في ذلك المفتاح للقراءة فقط، قراءة الاستخدام. راجع [Authentication](/api-reference/introduction#authentication) لمعرفة كيفية إنشاء مفتاح وضبط مستوى الوصول إليه.

لا تخزّن Dodo Payments النصوص أو الصور التي تفحصها ولا تكتبها في السجلات. ولكل فحص في الوضع المباشر، تحتفظ بالوقت والحكم و`request_id` الذي أرسلته لأغراض الفوترة وتقارير الاستخدام.

<CardGroup cols={2}>
  <Card title="Usage-Based Billing" icon="arrow-trend-up" href="/features/usage-based-billing/introduction">
    فوّتِر عملاءك أنت عن كل عملية إنشاء.
  </Card>

  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    بِع أرصدة الإنشاء واطرحها عند كل استخدام.
  </Card>
</CardGroup>