مرجع API

Moderations

محتوا را پیش یا پس از یک عملیات هوش مصنوعی بررسی کنید و نتیجه را مبنای سیاست محتوای اپلیکیشن خود قرار دهید.

روند کار

01بررسی ایمنی محتوا

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

بررسی ایمنی محتوا

POST/v1/moderations

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`input`	Body	string \| array<value>	الزامی	مشروط	یک رشته، فهرستی از رشته‌ها یا فهرستی از بخش‌های محتوا. فقط متن پذیرفته می‌شود؛ تصویر رد می‌شود، چون هنوز هیچ مسیری برای بررسی تصویر تأیید نشده است. تعداد موارد و طول هر مورد محدود است.
`model`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل بررسی محتوا. فقط وقتی اختیاری است که سرویس یک مدل پیش‌فرض برای آن تعیین کرده باشد؛ انتخاب خودکار وجود ندارد، چون نتیجهٔ بررسی فقط وقتی معنا دارد که بدانید کدام مدل آن را داده است.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/moderations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "input": "Text to classify."
}'

Response

{
  "id": "<id>",
  "model": "<value>",
  "results": [
    {
      "flagged": false,
      "categories": {},
      "category_scores": {},
      "category_applied_input_types": {}
    }
  ]
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402	موجودی برای پرداخت هزینه کافی نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409	تداخل در وضعیت یا idempotency.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.
502	سرویس ارائه‌دهنده با خطا مواجه شد.
503	یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.