openmoderate

Open-source, self-hosted image and video content moderation for Python. Detect nudity, sexual content, violence, gore, weapons, hate symbols, drugs, self-harm, alcohol and tobacco in uploaded images and videos — with one pip install, no cloud account, no per-image fees, and no ML experience needed.

Think of it as an open alternative to Amazon Rekognition's DetectModerationLabels that runs inside your own app.

from openmoderate import Moderator

mod = Moderator()
result = mod.analyze("upload.jpg")

if not result.is_safe:
    print(result.violations)
    # [Label(name='weapons', confidence=0.9612, parent='violence', threshold=0.5)]

Documentation · Benchmarks · Changelog · Security

Install

pip install openmoderate

Python 3.9+. The first call downloads the CLIP model weights (~600 MB) once; after that everything runs offline, on CPU, CUDA or Apple Silicon. Extras: openmoderate[server], [video], [fastapi], [flask], [django]. See the install notes for CPU-only servers.

What you can do with it

Pick the accuracy you need — Moderator(preset="accurate") uses a larger model: 82% recall with 4% of safe images flagged, versus 77% / 6.5% for the default (benchmarks).

Tune the policy — thresholds, categories and your own categories as plain text, no training data needed (guide):

mod = Moderator(thresholds={"weapons": 0.3}, exclude=["alcohol", "tobacco"])
mod = Moderator("policy.yaml")   # custom categories like "gambling" in YAML

Scan from the command line — folders, URLs and videos; --fail-on-violation for CI (guide):

openmoderate scan ./uploads

Train on your own images for better accuracy in your domain (guide):

openmoderate train ./dataset -o my_head.omh      # dataset/<label>/*.jpg + dataset/safe/

Moderate videos with timestamped segments (guide):

Moderator().analyze_video("clip.mp4").segments   # weapons 0:03–0:06, violence 0:09–0:12

Protect uploads in FastAPI, Flask or Django with one line (guide):

async def avatar(file: ModeratedFile): ...                          # FastAPI
avatar = models.ImageField(validators=[ModerationValidator()])      # Django

Call it over HTTP from any language — REST server and Docker image (guide):

docker run -p 8000:8000 -e OPENMODERATE_API_KEY=change-me ghcr.io/karammm/openmoderate
curl -H "X-API-Key: change-me" -F file=@upload.jpg localhost:8000/v1/moderate

Accuracy

Measured on a held-out set of hand-reviewed, openly licensed photos (full results and method, reproducible with python benchmark/run.py):

6% of safe images (including look-alikes such as kitchen knives, milk and medicine) were flagged. The accurate preset raises average recall to 82% while flagging 4%. Sets are small, so read these as ±10 points. Nudity, sexual content, gore and self-harm are not benchmarked by the maintainers — evaluate them on your own data.

Zero-shot moderation is good at clear-cut cases and will miss subtle ones. Evaluate on a sample of your own traffic, adjust thresholds, and send borderline scores to human review for high-stakes decisions. How it works and its limits.

Contributing

Contributions are welcome — better prompts, new categories, benchmark images and bug reports especially. See CONTRIBUTING.md. Report security issues privately (SECURITY.md).

Responsible use

openmoderate is meant to help keep platforms safe. Do not use it to surveil individuals or to profile people by protected characteristics. Moderation models make mistakes; give users a way to appeal automated decisions.

License

Apache 2.0. Benchmark images keep their own licences (see benchmark/manifest.csv).