Moderate a video | Mux

Moderate a video

Analyze a video for inappropriate content with the Mux Robots API. Use this workflow when your platform accepts user-generated video and you must review uploads.

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 reference for the full endpoint specification. See Mux Robots pricing for unit costs.

Create a moderate job

This request is asynchronous. The POST returns immediately with the job in pending status and does not include results. We strongly recommend listening for the robots.job.moderate.completed webhook — the payload contains the full completed job, so no follow-up API call is needed. If webhooks aren't an option, you can poll GET /robots/v0/jobs/moderate/{JOB_ID} with the id from the response until the status is completed.

Parameters

Parameter Type Description
asset_id string Required. The Mux asset ID of the video to moderate.
language_code string Language code for transcript analysis on audio-only assets. Defaults to en.
thresholds object Score thresholds that determine whether content is flagged.
thresholds.sexual number Score threshold (0.0-1.0) for sexual content. Defaults to 0.7.
thresholds.violence number Score threshold (0.0-1.0) for violent content. Defaults to 0.8.
sampling_interval integer Interval in seconds between sampled thumbnails. Minimum 5.
max_samples integer Maximum number of thumbnails to sample. Samples are distributed evenly across the video with the first and last frames pinned.
output_steering object Optional controls that restrict where moderation runs on the asset.
output_steering.scope object Time window in seconds on the asset timeline, with start_time and end_time.
on_flagged object Optional action to take automatically when exceeds_threshold is true.
on_flagged.action string The action to perform. Currently the only supported value is delete_playback_ids.

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.

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.

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.

Platform profile Suggested starting point
Open UGC, instant publishing sexual: 0.6, violence: 0.6, sampling_interval: 5, and a human review queue for scores near the threshold
Vetted uploaders, or a review delay before publishing The defaults: sexual: 0.7, violence: 0.8, sampling_interval: 10
Closed or internal platform sexual: 0.8, violence: 0.9, max_samples: 20

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.

Using sampling behavior to manage moderation cost

Each sample costs 100 units ($0.001); a job's total cost is just its sample count.

Configuration 10-minute video 1-hour video
sampling_interval: 5 120 samples ($0.12) 720 samples ($0.72)
sampling_interval: 10 60 samples ($0.06) 360 samples ($0.36)
max_samples: 20 20 samples ($0.02) 20 samples ($0.02)

Output

The outputs object is included in the job once its status is completed.

Field Type Description
thumbnail_scores array Per-thumbnail moderation scores, each with sexual and violence fields (0.0-1.0).
max_scores object Highest scores across all thumbnails, with sexual and violence fields.
exceeds_threshold boolean true if any category's max score exceeds its configured threshold.
flagged_action object Present only when on_flagged was set and exceeds_threshold was true.

Example response

Moderation works by sampling thumbnail frames from your video. You can control how many frames are analyzed with sampling_interval or max_samples. More samples give better coverage but increase processing time and cost.