راهنمای اتصال به API

Moderation API؛ تشخیص محتوای ناامن با omni-moderation و Llama Guard

اگر کاربران در محصول شما متن یا تصویر می‌فرستند، باید پیش از نمایش یا ارسال آن به مدل‌ها، محتوای ناامن را جدا کنید. مسیر POST /v1/moderations در وان ای آی (1ai) همان قالب OpenAI را دارد، پس client.moderations.create در کتابخانه‌ی رسمی openai بدون تغییر کار می‌کند. openai/omni-moderation-latest متن و تصویر را بررسی می‌کند و برای هر دسته امتیاز می‌دهد. مدل‌های گارد مثل meta-llama/llama-guard-3-8b هم از همین مسیر پاسخ می‌دهند و کدهای خطر Llama Guard به همان دسته‌ها تبدیل می‌شوند. اگر model را نفرستید، مدل پیش‌فرض بررسی محتوا به کار می‌رود.

چرا با 1ai

سازگار با OpenAI SDK

client.moderations.create در Python و Node.js با تغییر آدرس پایه به https://1ai.ir/v1 کار می‌کند.

متن و تصویر

omni-moderation تصویر را هم با image_url بررسی می‌کند و می‌گوید هر دسته روی کدام نوع ورودی اعمال شده است.

Llama Guard در همان قالب

پاسخ مدل گارد به flagged و categories تبدیل می‌شود و کدهای اصلی خطر در guard.codes می‌آید.

چند ورودی در یک درخواست

آرایه‌ای از متن‌ها بفرستید و برای هر کدام یک نتیجه به همان ترتیب بگیرید.

در چند قدم

  1. ۱

    کلید API بسازید

    از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.

  2. ۲

    مدل را انتخاب کنید

    برای متن و تصویر openai/omni-moderation-latest و برای سیاست‌های Llama Guard مدل گارد را از فهرست پایین بردارید.

  3. ۳

    ورودی را بفرستید

    متن، آرایه‌ای از متن‌ها یا بخش‌های text و image_url را در input بگذارید.

  4. ۴

    روی نتیجه عمل کنید

    اگر flagged درست بود محتوا را نگه دارید یا برای بررسی بفرستید؛ برای سخت‌گیری بیشتر روی category_scores آستانه بگذارید.

مدل‌های بررسی محتوا در API

همه‌ی مدل‌ها

Omni Moderation

اوپن‌ای‌آی
بررسی محتوا

تشخیص محتوای ناامن در متن و تصویر

۰ اعتبار / ۱۰۰۰ توکن ورودی
API
بررسی محتوا

گارد متنی با دسته‌های خطر Llama Guard

۰٫۰۷۲۶ اعتبار / ۱۰۰۰ توکن ورودی
API

نمونه درخواست با curl

bash
curl https://1ai.ir/v1/moderations \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai/omni-moderation-latest", "input": ["متن اول کاربر", "متن دوم کاربر"] }'

OpenAI SDK در Python و Node.js

python
# pip install openai
import os
from openai import OpenAI

client = OpenAI(base_url="https://1ai.ir/v1", api_key=os.environ["ONEAI_API_KEY"])

result = client.moderations.create(
    model="openai/omni-moderation-latest",
    input=[
        {"type": "text", "text": "Caption of the uploaded photo"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
    ],
)
print(result.results[0].flagged, result.results[0].categories)
javascript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://1ai.ir/v1", apiKey: process.env.ONEAI_API_KEY });
const { results } = await client.moderations.create({ model: "meta-llama/llama-guard-3-8b", input: userMessage });
if (results[0].flagged) console.log("blocked:", results[0].guard.codes);

قالب پاسخ

results برای هر متن ورودی یک نتیجه دارد؛ ورودی چندبخشی (متن و تصویر با هم) یک نتیجه می‌گیرد.

json
{
  "id": "modr-…",
  "model": "openai/omni-moderation-latest",
  "results": [
    {
      "flagged": true,
      "categories": { "violence": true, "harassment": false, "hate": false, "self-harm": false, "sexual": false, "illicit": false },
      "category_scores": { "violence": 0.92, "harassment": 0.012, "hate": 0.003 },
      "category_applied_input_types": { "violence": ["text"] }
    }
  ]
}

دسته‌ها: harassment، harassment/threatening، hate، hate/threatening، illicit، illicit/violent، self-harm، self-harm/intent، self-harm/instructions، sexual، sexual/minors، violence، violence/graphic.

مدل‌های گارد (Llama Guard)

Llama Guard برای هر ورودی یک حکم safe یا unsafe و کدهای خطر (مثل S1 برای جرم خشن یا S10 برای نفرت) می‌دهد. 1ai هر ورودی را جداگانه به مدل می‌دهد، کدها را به دسته‌های بالا تبدیل می‌کند و اصل حکم را در فیلد اضافه‌ی guard نگه می‌دارد:

json
{ "flagged": true, "categories": { "illicit/violent": true, "violence": true }, "category_scores": { "violence": 1 }, "guard": { "verdict": "unsafe", "codes": ["S9"] } }

مدل گارد احتمال نمی‌دهد، پس امتیازها صفر یا یک‌اند. هر درخواست به مدل گارد تا ۱۶ ورودی می‌پذیرد و هزینه‌اش بر اساس توکن حساب می‌شود.

فیلدهای درخواست

فیلدنوعتوضیح
modelرشته، اختیاریشناسه‌ی مدل بررسی محتوا؛ بدون آن مدل پیش‌فرض
inputرشتهیک متن
inputآرایه‌ی رشته (تا ۲۵۶)چند متن، هر کدام یک نتیجه
inputآرایه‌ی بخش‌ها (تا ۳۲){ "type": "text" } و { "type": "image_url" } برای یک ورودی چندرسانه‌ای

سوالات متداول

کد فعلی‌ام با OpenAI moderation کار می‌کند؛ چه چیزی عوض می‌شود؟

فقط آدرس پایه (https://1ai.ir/v1)، کلید (sk-1ai-…) و شناسه‌ی مدل که پیشوند سازنده دارد، مثل openai/omni-moderation-latest. اگر model را نفرستید هم درخواست با مدل پیش‌فرض اجرا می‌شود.

omni-moderation را انتخاب کنم یا Llama Guard؟

omni-moderation تصویر را هم بررسی می‌کند و برای هر دسته امتیاز پیوسته می‌دهد. Llama Guard فقط متن را می‌خواند و حکم قطعی با کد خطر می‌دهد؛ اگر سیاست شما بر دسته‌های Llama Guard تعریف شده، آن را به کار ببرید.

هزینه‌ی بررسی محتوا چقدر است؟

قیمت هر مدل در صفحه‌ی همان مدل آمده است. هر درخواست در گزارش مصرف ثبت می‌شود و اعتبار کسرشده‌ی آن در سرآیند x-1ai-credits است.

متن فارسی را هم تشخیص می‌دهد؟

هر دو مدل چندزبانه‌اند، اما دقت روی هر زبان یکسان نیست. چند نمونه‌ی واقعی از محتوای کاربران خودتان را آزمایش کنید و آستانه‌ها را بر همان اساس تنظیم کنید.

مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

۴ دقیقه مطالعه
همه‌ی امکانات

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

Decisions API

به جای تجزیه‌ی متن آزاد مدل، پرسش‌هایتان را تعریف کنید و برای هر کدام پاسخی تایپ‌دار بگیرید: احتمال درستی یک گزاره، گزینه‌ی انتخاب‌شده یا امتیاز روی یک مقیاس.

اتصال Open WebUI

Open WebUI را روی سرور خودتان بالا بیاورید، یک اتصال OpenAI با آدرس 1ai بسازید و برای کاربرانتان رابط چت با GPT، Claude، Gemini و DeepSeek داشته باشید.

Moderation API؛ تشخیص محتوای ناامن با omni-moderation و Llama Guard

پیش از نمایش یا پردازش محتوای کاربر، آن را بررسی کنید: برای هر ورودی پرچم ناامن، دسته‌های نقض‌شده و امتیاز هر دسته را بگیرید.

ساخت کلید API