Analyze a video for inappropriate content. Mux samples thumbnails from the video and scores each one for sexual and violent content. You can configure the thresholds that determine whether content gets flagged. See the Moderate API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.

Create a moderate job

curl https://api.mux.com/robots/v0/jobs/moderate \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "thresholds": {
        "sexual": 0.7,
        "violence": 0.8
      }
    }
  }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Parameters

Sampling behavior

By default, the workflow samples a thumbnail every 10 seconds. Use sampling_interval to override this; the minimum is 5 seconds. Smaller intervals give denser coverage at higher cost; larger intervals are cheaper but may miss brief moments of flagged content.

For example, with sampling_interval: 10, a 60-second video produces 6 samples — at 0, 10, 20, 30, 40, and 50 seconds.

If you set max_samples alongside sampling_interval, the cap takes over once the interval would produce more samples than allowed. See the parameter descriptions above.

Choose a sampling interval and thresholds

The defaults (sexual: 0.7, violence: 0.8, one sample every 10 seconds) are a reasonable starting point. The right configuration depends on your platform's risk model: who can upload, how quickly content becomes public, who your audience is, and the impact to your business of a missed detection compared to an incorrect takedown.

Establishing a risk model

Open UGC platforms where anyone can sign up and publish immediately carry the most risk and warrant the strictest settings. Platforms with vetted uploaders or a publishing delay can lean on the defaults. Closed platforms (internal video, course content, fitness apps) are mostly guarding against account compromise and mistakes, and can prioritize cost instead.

For zero-tolerance audiences, such as platforms for children, go stricter still, like the thresholds in the strict moderation example below. Whatever you pick, compare your first few hundred jobs against the calls your human reviewers actually make, then adjust.

Understanding scores returned by the moderation model

A thumbnail's score is how confident the model is that the category is present in that frame, not how extreme the content is. Clearly visible but mild nudity can score higher than graphic violence in a dark, partially obscured shot. That distinction matters when you pick thresholds:

• A threshold is a confidence bar, not a severity dial. Lowering sexual from 0.7 to 0.5 doesn't redefine what counts as sexual content; it flags frames the model is less certain about. You'll catch more borderline content, and more false positives.
• Don't map score bands to punishment tiers. A 0.9 isn't "worse" than a 0.75; the model is just more sure. Use the score to decide whether a human looks at the video, and let the human judge severity against your content policy.
• Reserve automated actions for high-confidence flags. If you use on_flagged to unpublish content automatically, pair it with thresholds high enough that you can tolerate acting without review.

Using sampling behavior to manage moderation cost

Each sample costs 100 units ($0.001); a job's total cost is just its sample count. The two controls described in Sampling behavior determine that count in opposite ways:

• sampling_interval fixes coverage; cost scales with duration. One sample every N seconds means no stretch of video longer than N seconds goes unchecked, whether the upload is two minutes or two hours. Use it when you want a coverage guarantee and can let spend vary per video.
• max_samples fixes cost; coverage thins as videos get longer. The same N samples are spread evenly across the video, with the first and last frames pinned, so a long upload costs the same as a short one but leaves wider gaps between samples. Use it when you need a predictable worst-case cost per video, especially when upload durations vary widely.

You can also combine them: set sampling_interval for the coverage you want and max_samples as a spending cap that takes over on long videos. For example, sampling_interval: 10 with max_samples: 60 gives full 10-second coverage on videos up to 10 minutes, and caps any longer video at $0.06.

How dense you need to go depends on what you're screening for:

• Sexual content is rarely hidden. Uploaders generally aren't burying a few seconds of nudity inside an otherwise innocent video. When it's present, it tends to run through much of the content, so sparse sampling (a max_samples cap, or a 30-60 second interval) still hits it with high probability.
• Violence is more often brief. A fight in a live stream recording or a single violent scene can fit between sparse samples. If violence is your primary risk, spend on a denser interval instead.

Using multiple passes to re-inspect borderline content

Rather than paying for dense sampling on every upload, one option is to run a cheap first pass on everything and spend more only where the results are ambiguous:

1. First pass: run every upload with sparse sampling (say max_samples: 20) and your normal thresholds.
2. Clear results: publish videos that score well below your thresholds; flag or action videos above them.
3. Ambiguous results: when max_scores lands just under a threshold (within 0.2 of it, for example), run a second moderate job with sampling_interval: 5. Use output_steering.scope to restrict the second pass to the region around the suspicious samples in thumbnail_scores instead of re-scanning the whole video.

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "sampling_interval": 5,
    "output_steering": {
      "scope": {
        "start_time": 120,
        "end_time": 300
      }
    }
  }
}

Most uploads on most platforms are innocuous, so the bulk of your library clears at the first-pass price of $0.02 per video, and only the ambiguous few need a second job.

Maintaining a human reporting path

No sampling interval catches everything, and no threshold gets every judgment right. Treat automated moderation as triage, not a verdict: route borderline scores to a human review queue, and give users a way to report content that slips through. At minimum, that's in-product reporting and a dedicated abuse address. See contact mechanisms and the other operational strategies in the Moderate video content guide.

Output

The outputs object is included in the job once its status is completed. You'll receive it on the robots.job.moderate.completed webhook (recommended), or you can fetch it with GET /robots/v0/jobs/moderate/{JOB_ID}. It contains:

Example response

This is the payload delivered to the robots.job.moderate.completed webhook, and the same shape you get from GET /robots/v0/jobs/moderate/{JOB_ID}:

{
  "data": {
    "id": "rjob_def456",
    "workflow": "moderate",
    "status": "completed",
    "units_consumed": 1,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "thresholds": {
        "sexual": 0.7,
        "violence": 0.8
      }
    },
    "outputs": {
      "thumbnail_scores": [
        { "time": 0.0, "sexual": 0.01, "violence": 0.02 },
        { "time": 5.0, "sexual": 0.03, "violence": 0.05 }
      ],
      "max_scores": {
        "sexual": 0.03,
        "violence": 0.05
      },
      "exceeds_threshold": false
    }
  }
}

Example: strict moderation

If content safety is critical for your platform, lower the thresholds and increase the sample density:

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "thresholds": {
      "sexual": 0.3,
      "violence": 0.4
    },
    "max_samples": 50
  }
}

With lower thresholds, even mildly suggestive or mildly violent content will cause exceeds_threshold to return true, giving you a signal to flag the video for human review before publishing.

Take action on flagged content

By default, a moderate job only reports scores — it never changes your asset. Set on_flagged to have the workflow act automatically when exceeds_threshold is true:

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "thresholds": {
      "sexual": 0.3,
      "violence": 0.4
    },
    "on_flagged": {
      "action": "delete_playback_ids"
    }
  }
}

When the content exceeds a threshold, delete_playback_ids removes every playback ID on the asset, making it immediately unplayable while preserving the underlying master asset so you can review it and re-publish later by creating a new playback ID.

The action is best-effort and non-fatal: if a deletion fails, the job still completes with its moderation scores rather than erroring. The outcome is reported back in the job output as flagged_action:

{
  "outputs": {
    "max_scores": {
      "sexual": 0.82,
      "violence": 0.10
    },
    "exceeds_threshold": true,
    "flagged_action": {
      "action": "delete_playback_ids",
      "deleted_playback_ids": ["abc123...", "def456..."]
    }
  }
}