# hate-speech-detection

> Hate Speech Detection scores text and images for hate speech and dehumanizing language targeting protected groups, returning a yes/no verdict in a single synchronous call. Powered by a self-hosted Shieldstral-1.0-3B safety classifier, it reads 12 languages natively — no translation step — and every verdict carries a 0-1 confidence score so you can set your own bar.

- **Provider:** AirCube
- **Category:** moderation
- **Price:** $0.0010 per run

## Key Features

- Sub-second verdicts — a single image comes back in roughly 400-500ms, measured end to end against production hardware. No queue, no job id, no polling loop.
- Synchronous by design — one HTTP call in, the answer out. Unlike generation endpoints there is nothing to poll and no webhook to wire up.
- Text and images through one endpoint — the same classifier reads them all, so you screen an upload, its caption and its thumbnail without stitching three vendors together.
- 12 languages natively — English, Chinese, Japanese, Korean, French, Spanish, German, Italian, Portuguese, Dutch, Arabic and Russian. No translation step, no per-language model.
- Frame-by-frame video scanning with early exit — a clip is sampled into evenly spaced frames and checking stops the instant one crosses your threshold, so flagged videos return in about a second instead of scanning to the end.
- A calibrated 0-1 score behind every verdict, not just a boolean — read it off the yes/no token logits so you can auto-approve, auto-block and route only the grey zone to humans.
- Your policy, your bar — the threshold is a request parameter. Tighten it for a kids' app, loosen it for an adult platform, without changing anything else.
- Dedicated GPUs, self-hosted — a Shieldstral-1.0-3B safety classifier we run ourselves. No third-party moderation vendor sees your users' content.
- $0.001 per call, flat — image, video or text, one second or ten minutes of footage, the same price.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `image_url` | One of the three | Public http(s) URL of an image. |
| `video_url` | One of the three | Public http(s) URL of a video. Maximum 200 MB. |
| `text` | One of the three | Plain text to classify. Up to 20,000 characters, any of the 12 supported languages. |
| `policy` | Yes | Set to `hate` for this model. Omitting it falls back to `nsfw`. |
| `threshold` | No | Score at or above which content counts as a violation. 0-1, default 0.5. |
| `max_frames` | No | Video only. How many frames to sample. 1-16, default 8. |

## How to Use

1. POST to /api/v3/moderation with your API key, `policy: "hate"`, and exactly one of image_url, video_url or text.
2. Read data.nsfw — that is the yes/no answer. If that is all you need, ignore the rest of the response.
3. Use data.score (0-1) when you want a grey zone: auto-approve low scores, auto-block high ones, queue the middle for human review.
4. For videos, data.frames lists each checked frame's timestamp and score, so you can see exactly where the problem is.
5. Check data.duration_ms if you are budgeting latency — it is the server-side processing time, excluding your own round trip.

## Code Examples

### Python

```python
import os
import requests

API_KEY = os.environ["AIRCUBE_API_KEY"]

res = requests.post(
    "https://aircube.ai/api/v3/moderation",
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
    json={"image_url": "https://example.com/photo.jpg", "policy": "hate"},
    timeout=300,
)
data = res.json()["data"]

print("NSFW" if data["nsfw"] else "Safe", data["score"])
```

### JavaScript

```javascript
const res = await fetch("https://aircube.ai/api/v3/moderation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRCUBE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_url: "https://example.com/clip.mp4",
    policy: "hate",
    threshold: 0.5,
    max_frames: 8,
  }),
});

const { data } = await res.json();
console.log(data.nsfw ? "NSFW" : "Safe", data.score);
```

### cURL

```bash
curl -X POST https://aircube.ai/api/v3/moderation \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg", "policy": "hate"}'

# { "success": true, "data": { "nsfw": false, "score": 0.0141,
#   "threshold": 0.5, "media_type": "image", "policy": "hate" } }
```

## Pricing

| Resolution | Duration | Cost |
| --- | --- | --- |
| Image, video or text | per call | $0.0010 |

### Billing Rules

- $0.001 per call — the same flat rate for an image, a video of any length, or up to 20,000 characters of text.
- The first 10 calls on your account are free.
- Because $0.001 is a tenth of a cent, calls are settled in batches: every 10 calls costs 1 cent.
- Video is billed per call, not per frame: sampling 16 frames costs the same as sampling 4.
- One call checks one policy. Screening for several means several calls, each billed separately.
- Failed calls are not charged and do not count toward a batch.

## Best Use Cases

- Comments and chat — screen posts before they go live.
- Multilingual communities — one endpoint covers 12 languages, no translation step.
- Generation pipelines — check model output before returning it.
- Tiered review — auto-block the clear cases, send the grey zone to humans.

## Pro Tips

- The default threshold of 0.5 works for a general-audience platform. See the score table below to pick your own.
- Raising max_frames is close to free on flagged videos — early exit means a bad clip still returns after the first hit. It only costs latency on clean ones.
- Set threshold to 1 to force every frame to be scored — useful when profiling content or calibrating your own cut-off.
- Store the score, not just the boolean. It lets you re-tune your threshold later without re-processing anything.
- Screening for more than one policy? Fire the calls in parallel rather than in sequence — they are independent.

## Notes

- Validation status — Fully validated on text, in both English and Chinese, including the trap that matters most: criticism is not hate. Disagreeing with a country's foreign policy scores 0.02 and a negative restaurant review 0.04, while dehumanizing statements about a group score 0.85+. Images have not been verified for true positives yet — use it on text with confidence, and validate your own images before extending it there.
- URLs must be publicly reachable over http(s). Data URIs and direct file uploads are not accepted by the API.
- Videos must be 200 MB or smaller; text up to 20,000 characters.
- Scores are probabilistic — for high-stakes decisions, pair the API with human review of borderline results.

## FAQ

**Q: What does the Hate Speech Detection API do?**

Hate Speech Detection scores text and images for hate speech and dehumanizing language targeting protected groups, returning a yes/no verdict in a single synchronous call. Powered by a self-hosted Shieldstral-1.0-3B safety classifier, it reads 12 languages natively — no translation step — and every verdict carries a 0-1 confidence score so you can set your own bar.

**Q: How fast is it?**

An image or a block of text comes back in roughly 400-500ms. A video takes about a second per sampled frame, and checking stops as soon as one frame is flagged.

**Q: How well has it been tested?**

Fully validated on text, in both English and Chinese, including the trap that matters most: criticism is not hate. Disagreeing with a country's foreign policy scores 0.02 and a negative restaurant review 0.04, while dehumanizing statements about a group score 0.85+. Images have not been verified for true positives yet — use it on text with confidence, and validate your own images before extending it there.

**Q: Which languages are supported?**

English, Chinese, Japanese, Korean, French, Spanish, German, Italian, Portuguese, Dutch, Arabic and Russian — natively, in one model.

**Q: How are videos handled?**

The video is downloaded and sampled into up to max_frames evenly spaced frames. Each is scored in turn, the overall score is the highest frame score, and checking stops at the first frame above your threshold.

**Q: Can I check several policies at once?**

Not in one call — each call checks one policy. Send the requests in parallel; each is billed separately at $0.001.

**Q: What does it cost?**

$0.001 per call, flat — regardless of media type or video length. Your first 10 calls are free. Since a tenth of a cent cannot be deducted on its own, calls settle in batches of 10 for 1 cent.

**Q: Can I upload a file directly?**

Not through the API — it takes public http(s) URLs only. The in-app tool does accept direct uploads.
