راهنمای شروع سریع

برای مدیریت محتوا با Discuse، یک درخواست POST به https://api.discuse.com/api/v2/check همراه با هدر X-API-Key و یک بدنه JSON شامل متن، URLهای تصویر یا URLهای فایل‌هایی که می‌خواهید بررسی شوند ارسال کنید. پاسخ، جزئیات را به تفکیک هر دسته و یک پرچم واحد has_violations برمی‌گرداند. این راهنما شما را در اولین فراخوانی، قالب پاسخ و مدیریت خطاهای پایه همراهی می‌کند — از ابتدا تا انتها حدود پنج دقیقه زمان می‌برد.

پیش‌نیازها

پیش از شروع، مطمئن شوید که موارد زیر را دارید:

1. یک حساب Discuse (در discuse.com ثبت‌نام کنید)
2. یک کلید API از داشبورد خود
3. ابزاری برای ارسال درخواست‌های HTTP (cURL، Postman یا کد برنامه شما)

مرحله ۱: دریافت کلید API

پس از ثبت‌نام، به داشبورد خود بروید و بخش API Keys را پیدا کنید. برای ساخت یک کلید API جدید، روی "Create New Key" کلیک کنید. این کلید را امن نگه دارید - این کلید دسترسی به حساب و سهمیه مصرف شما را فراهم می‌کند.

هر کلید Discuse با پیشوند disc_ شروع می‌شود، برای مثال:

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

مرحله ۲: اولین فراخوانی API خود را انجام دهید

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

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "Hello, this is a test message to analyze!"
    }
  }'

مرحله ۳: پاسخ را درک کنید

یک درخواست موفق، یک پاسخ JSON همراه با نتایج تحلیل برمی‌گرداند:

{
  "has_violations": false,
  "cached": false,
  "results": {
    "hits": false,
    "sentiment": {
      "is_negative": false,
      "is_toxic": false,
      "score": 0.03,
      "toxic": 0.02,
      "profanity": 0.01,
      "threat": 0.00,
      "insult": 0.03,
      "hit": false
    },
    "spamfinder": {
      "label": "ham",
      "confidence": 0.08,
      "is_spam": false,
      "hit": false
    },
    "language": {
      "language": "en",
      "confidence": 0.98
    }
  },
  "usage": {
    "api_requests_used": 42,
    "api_requests_limit": 1000,
    "api_requests_remaining": 958
  }
}

processing_time_ms فقط زمانی درج می‌شود که زمان‌سنجی در تنظیمات پروژه شما فعال باشد، و message فقط در پاسخ‌های مربوط به عبور از سهمیه تنظیم می‌شود — بنابراین هر دو از مثال بالا حذف شده‌اند.

توضیح فیلدهای پاسخ

فیلد	توضیح
has_violations	مقدار بولی: اگر هر بررسی فعال محتوا را علامت‌گذاری کرده باشد true است (معادل results.hits)
cached	مشخص می‌کند آیا این نتیجه از کش ارائه شده است یا نه (همچنان یک درخواست از سهمیه کم می‌شود)
results.hits	پرچم کلی شناسایی در تمام بررسی‌ها
results.sentiment	امتیازهای سمی‌بودن از 0.0 (ایمن) تا 1.0 (بسیار سمی)، به‌همراه پرچم‌های تصمیم‌گیری is_toxic/hit
results.spamfinder	نتیجه تشخیص اسپم: label، confidence، is_spam (خام) و hit (با درنظرگرفتن آستانه)
results.language	کد language شناسایی‌شده و confidence
usage	تعداد درخواست‌های API شما، سقف مجاز و سهمیه باقی‌مانده برای دوره صورتحساب فعلی

مرحله ۴: تحلیل یک تصویر

برای بررسی یک تصویر از نظر محتوای NSFW، URL تصویر را در درخواست خود قرار دهید:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "image_urls": ["https://example.com/image.jpg"]
    },
    "settings": {
      "check_images": true
    }
  }'

مرحله ۵: ترکیب چند بررسی

می‌توانید متن و تصاویر را با هم در یک درخواست واحد تحلیل کنید:

{
  "content": {
    "text": "Check out this amazing photo!",
    "image_urls": ["https://example.com/photo.jpg"]
  },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_images": true,
    "check_language": true
  }
}

نمونه‌های یکپارچه‌سازی

JavaScript/Node.js

async function checkContent(text) {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({
      content: { text }
    })
  });

  return response.json();
}

// Usage
const result = await checkContent('Hello world!');
if (result.has_violations) {
  console.log('Content flagged:', result.message);
}

Python

import requests
import os

def check_content(text):
    response = requests.post(
        'https://api.discuse.com/api/v2/check',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={
            'content': {'text': text}
        }
    )
    return response.json()

# Usage
result = check_content('Hello world!')
if result['has_violations']:
    print(f"Content flagged: {result['message']}")

آیا کش شدن در سهمیه من حساب می‌شود؟

Discuse نتایج محتوای یکسان را برای چند دقیقه کش می‌کند. وقتی پاسخی با "cached": true برمی‌گردد، یعنی از کش ارائه شده است؛ بنابراین سریع‌تر بازمی‌گردد و بررسی‌ها دوباره اجرا نمی‌شوند. این درخواست همچنان به‌عنوان یک درخواست API از سهمیه شما کم می‌شود، اما بابت اسکن‌های زیربنایی هر قابلیت (تصویر، آنتی‌ویروس) دوباره هزینه‌ای محاسبه نمی‌شود. کش عمدتاً زمانی مفید است که یک محتوای یکسان در یک بازه کوتاه بارها ارسال شود.

چگونه خطاها را مدیریت کنم؟

یک بررسی موفق، HTTP 200 برمی‌گرداند. کلید ناموفق، محدودیت نرخ یا درخواست بدفرم، یک وضعیت غیر 2xx برمی‌گرداند. توجه داشته باشید که تمام شدن سهمیه یک خطای HTTP نیست: وقتی سهمیه دوره صورتحساب شما مصرف شود، API همچنان 200 را با has_violations: false و یک message که توضیح می‌دهد سهمیه تمام شده است برمی‌گرداند — به‌جای اتکا به کد وضعیت، فیلدهای message و usage را بررسی کنید.

try {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify({ content: { text } })
  });

  if (!response.ok) {
    if (response.status === 401 || response.status === 403) {
      throw new Error('Invalid or unauthorized API key');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded - slow down requests');
    }
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();

  // Quota exhaustion is returned as a 200 with a message, not an error status.
  if (result.message && result.usage && result.usage.api_requests_remaining === 0) {
    console.warn('Quota exceeded:', result.message);
  }

  return result;
} catch (error) {
  console.error('Content check failed:', error);
  throw error;
}

گام‌های بعدی

حالا که اولین فراخوانی API خود را انجام داده‌اید، این منابع را بررسی کنید:

• احراز هویت و کلیدهای API - درباره مدیریت امن کلیدها بیاموزید
• تحلیل متن - بررسی عمیق تشخیص احساسات و اسپم
• تشخیص NSFW تصویر - از پلتفرم خود در برابر تصاویر نامناسب محافظت کنید
• پیکربندی آستانه‌ها - حساسیت تشخیص را دقیق‌تر تنظیم کنید