Moderation API

Screen a Prompt

أرسل نصًا أو صورة أو كليهما، واحصل على حكم.

Get Moderation Usage

اطّلع على عمليات الفحص القابلة للفوترة ورسومك التالية.

نظرة عامة

يفحص 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 أدوات إنشاء المحتوى بالذكاء الاصطناعي ولا تسمح بانتحال الشخصية أو التزييف العميق أو المحتوى الصريح، بما في ذلك المحتوى المُنشأ بالذكاء الاصطناعي. قد يُوضع الحساب الذي ينشئ محتوى ضارًا أو يتسبب في عمليات رد مبالغ مفرطة أو إشعارات من شركاء الدفع قيد المراجعة أو يُعلّق. أنشأنا Moderation API حتى تتمكن من إيقاف هذا المحتوى قبل أن ينشئه نموذجك:

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

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

آلية العمل

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

الأحكام

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

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

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

فحص مطالبة

لفحص مطالبة، أرسل طلب 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 أو أي خطأ:

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

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);
}

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)

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

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

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

فحص الصور

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

التنسيق هو 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 من المثال السابق:

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';
}

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"

# 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 @-

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

قراءة الرد

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

الحقل	الوصف
`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 والتنسيق، لكنه لا يتحقق من عدد الإطارات أو الأبعاد. قبل الانتقال إلى الوضع المباشر، تأكد من أن تكاملك يتعامل مع كل حالة:

Deny Blocks Generation

أرسل dodo_mock_deny وتأكد من عدم استدعاء نموذجك.

Flag Follows Your Policy

أرسل dodo_mock_flag وتأكد من أن منتجك ينفذ ما تنص عليه سياستك.

Overload Retries

أرسل dodo_mock_overloaded وتأكد من أن شفرتك تنتظر Retry-After ولا تنشئ المحتوى دون حكم.

An Outage Blocks Generation

أرسل dodo_mock_not_ready وتأكد من عدم استدعاء نموذجك.

Every Generation Path Screens

تحقق من أن كل مسار في الشفرة يصل إلى نموذجك يستدعي Moderation API أولًا.

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

تبلغ تكلفة Moderation API 0.30 دولار أمريكي لكل 1,000 فحص قابل للفوترة. لا توجد فئة مجانية ولا حد أدنى. الفحص القابل للفوترة هو فحص في الوضع المباشر يعيد حكمًا. وتكون الفحوص التالية مجانية ولا تُحتسب:

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

تُصدر Dodo Payments فواتير عن كتل كاملة من 1,000 فحص. تُحتسب رسوم كل كتلة كاملة خلال ساعة واحدة، بينما تظل الفحوص التي لا تكمل كتلة غير مفوترة حتى تكملها. تُخصم الرسوم من رصيدك بالدولار الأمريكي وتظهر في سجل الرصيد مع نوع الحدث moderation_fees. وتظهر في الدفعات تحت رسوم الإشراف.

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

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

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

curl https://live.dodopayments.com/moderation/usage \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

const usage = await client.moderation.retrieveUsage();
console.log(usage.unbilled_screens, usage.screens_to_next_block);

usage = client.moderation.retrieve_usage()
print(usage.unbilled_screens, usage.screens_to_next_block)

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

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

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

Usage-Based Billing

فوّتِر عملاءك أنت عن كل عملية إنشاء.

Credit-Based Billing

بِع أرصدة الإنشاء واطرحها عند كل استخدام.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Screen a Prompt

Get Moderation Usage

نظرة عامة

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

آلية العمل

الأحكام

فحص مطالبة

فحص الصور

قراءة الرد

الفئات

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

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

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

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

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

Usage-Based Billing

Credit-Based Billing

Screen a Prompt

Get Moderation Usage

​نظرة عامة

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

​آلية العمل

​الأحكام

​فحص مطالبة

​فحص الصور

​قراءة الرد

​الفئات

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

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

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

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

​الوصول والخصوصية

Usage-Based Billing

Credit-Based Billing

نظرة عامة

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

آلية العمل

الأحكام

فحص مطالبة

فحص الصور

قراءة الرد

الفئات

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

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

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

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

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