# Nova AI - Content Moderation API

The Content Moderation API allows you to analyze text content for policy violations, harassment, hate speech, and other harmful signals. It returns structured safety assessments with confidence scores, severity levels, and actionable recommendations.

> [!IMPORTANT]
> **Dedicated Endpoint**
> This feature uses a specialized endpoint optimized for safety classification. It is separate from the standard Chat Completions API.

## Endpoint

**POST** `https://novaaiapi.nabzclan.vip/v1/moderation`

## Pricing

| Type | Price |
|------|-------|
| **Input** | $0.11 / 1k tokens |
| **Output** | $0.13 / 1k tokens |

## Authentication

Include your API key in the `Authorization` header:

```bash
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

### Required
- **content** (string): The text content to analyze. Max 50,000 characters.

### Optional
- **policy** (string): Custom moderation policies to append to the model's base rules. 
  - Format: `#policy 1: description`. 
  - Max 10,000 characters.
- **instructions** (string): Additional instructions for the specific request (e.g., "max ban 10 days", "be lenient"). 
  - Max 2,000 characters.

## Response Format

The API returns a JSON object with the moderation assessment:

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | Overall verdict: `ALLOWED` or `DISALLOWED` |
| `category` | string | `SAFE`, `PROFANITY`, `SPAM`, `HARASSMENT`, `PII`, `SEXUAL`, `HATE_SPEECH`, `SELF_HARM`, `VIOLENCE`, `ILLEGAL`, `EXTREMISM`, `CHILD_SAFETY` |
| `severity` | string | Risk level: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` |
| `action` | string | Recommended action: `ALLOW`, `BLOCK`, `REDACT`, `ESCALATE`, `LOG_ONLY`, `BANNED` |
| `banned_days` | int/null | Suggested ban duration if applicable (e.g., 365 for zero-tolerance) |
| `reason` | string | Explanation of the decision |
| `confidence` | float | Model confidence score (0.00 - 1.00) |
| `uncertainty_flag` | boolean | True if model is uncertain (human review recommended) |
| `ambiguity_reason` | string | Reason for uncertainty: `NONE`, `CONTEXT_MISSING`, `SATIRE`, `QUOTED_CONTENT`, `MIXED_SIGNALS` |
| `escalation_required` | boolean | True if human review is strictly recommended |
| `auto_fail` | boolean | True if content triggered zero-tolerance policy |
| `detected_signals` | array | List of specific policy triggers found |
| `policy_version` | string | Version of the policy used |
| `timestamp` | string | ISO 8601 timestamp |
| `usage` | object | Token usage stats |

## Escalation Rules

1. **Zero-Tolerance Escalation (AutoFail)**
   - **Child Safety:** Any sexual exploitation of minors triggers `CRITICAL` severity, `BANNED` action, and 365-day ban.
   - **Terrorism / Extremism:** Credible threats or detailed violence planning trigger `CRITICAL` severity and immediate ban.

2. **Cumulative Signals**
   - If **3 or more** minor risk signals (e.g., mild threats, spam, profanity) appear together:
     - Severity escalates by one level (e.g., LOW -> MEDIUM).
     - If severity reaches CRITICAL, the action defaults to BANNED.

3. **Confidence Logic**
   - **Zero-Tolerance:** Confidence is always `1.00`.
   - **Ambiguity:** If conflicting signals exist, `uncertainty_flag` is set to true and confidence is lowered.

## Examples

### 1. Basic Content Check

```bash
curl -X POST https://novaaiapi.nabzclan.vip/v1/moderation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, how are you doing today?"
  }'
```

### 2. Custom Policies & Instructions

```bash
curl -X POST https://novaaiapi.nabzclan.vip/v1/moderation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are stupid &%^$",
    "policy": "#policy 1: block all insults\n#policy 2: ban 7 days for slurs",
    "instructions": "max ban should be 10 days, be strict"
  }'
```

### 3. Python Example

```python
import requests

url = "https://novaaiapi.nabzclan.vip/v1/moderation"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "content": "Text to moderate...",
    "policy": "#policy 1: block spam",
    "instructions": "prioritize safety"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result.get("status") == "ALLOWED":
    print(f"✅ Safe (Confidence: {result.get('confidence')})")
else:
    print(f"❌ Blocked: {result.get('reason')}")
```

### 4. Node.js Example

```javascript
const moderate = async () => {
  const response = await fetch('https://novaaiapi.nabzclan.vip/v1/moderation', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: 'Text to check...',
      policy: '#policy 1: no spam'
    })
  });

  const result = await response.json();
  console.log(result);
};
```

## Use Cases

- **Chat & Messaging:** Screen messages in real-time to prevent harassment.
- **AI Chatbots:** Filter inputs and outputs to ensure safety.
- **User-Generated Content:** Review posts, comments, and bios.
- **Gaming:** Moderate in-game chat and usernames.
- **Compliance:** Monitor internal comms for policy violations.

## Error Handling

- **400 Bad Request:** Missing or invalid `content`.
- **401 Unauthorized:** Invalid API key.
- **503 Service Unavailable:** Content moderation model not available.

## Best Practices

- Always check `uncertainty_flag` and `escalation_required`. If true, route for human review.
- Combine `policy` and `instructions` for fine-grained control over the model's strictness.