Moderation / Video moderation
Moderation

Video moderation

Video moderation with the Detectivision API: send the file or its URL, choose the frame rate, get back the flags it raised and when and where each finding is.

On this page

Send the video as a file, up to 20 MB, or by its URL, up to 100 MB. Detectivision samples frames at the rate you choose with fps, checks each one, and tells you what was found, when and where. A check pays per started 60 frames checked: a minute of video at fps: 1.

Send the video#

As a file#

Send a form (multipart/form-data) with the video in the field file and the other fields beside it, as text. Let your HTTP client write the form's Content-Type: it adds the boundary.

curl https://api.detectivision.ai/api/v1/moderation \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -F "type=video_moderation" \
  -F "fps=2" \
  -F "file=@clip.mp4"
import os, requests

with open("clip.mp4", "rb") as f:
    r = requests.post(
        "https://api.detectivision.ai/api/v1/moderation",
        headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
        data={"type": "video_moderation", "fps": "2"},
        files={"file": f},
        timeout=180,
    )
print(r.json())
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("type", "video_moderation");
form.append("fps", "2");
form.append("file", new Blob([await readFile("clip.mp4")], { type: "video/mp4" }), "clip.mp4");

const res = await fetch("https://api.detectivision.ai/api/v1/moderation", {
  method: "POST",
  headers: { "Api-Key": process.env.DETECTIVISION_API_KEY },
  body: form,
  signal: AbortSignal.timeout(180_000),
});
console.log(await res.json());

A service that already holds the video needs no URL for it: a bot that receives a user's clip, for example from Telegram, can send the file as it is. The form takes the same fields as an image's.

By URL#

Send the address of the video as input. Videos larger than 20 MB, up to 100 MB, go this way.

curl https://api.detectivision.ai/api/v1/moderation \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "video_moderation", "input": "https://example.com/clip.mp4", "fps": 2}'
import os, requests

r = requests.post(
    "https://api.detectivision.ai/api/v1/moderation",
    headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
    json={"type": "video_moderation", "input": "https://example.com/clip.mp4", "fps": 2},
    timeout=180,
)
print(r.json())
const res = await fetch("https://api.detectivision.ai/api/v1/moderation", {
  method: "POST",
  headers: { "Api-Key": process.env.DETECTIVISION_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ type: "video_moderation", input: "https://example.com/clip.mp4", fps: 2 }),
  signal: AbortSignal.timeout(180_000),
});
console.log(await res.json());

Note

A video check is answered when it is done, usually in seconds and at most about two minutes for a long, high-fps video. Use a generous client timeout (for example 180 seconds).

A video goes as a file or by its URL, which carry it as it is: in base64 it would be a third larger. A file is checked and not stored; only its name is kept with the request (upload: clip.mp4). An async one is kept only until its check runs, at most 24 hours.

Requirements#

File The field file of a multipart/form-data body, up to 20 MB. A file sent as application/octet-stream or without a type of its own is recognised by its first bytes.
URL An http:// or https:// URL reachable from the internet, downloaded with the user agent DetectivisionBot/1.0 (+https://detectivision.ai). The server must answer with a video/… content type.
Formats MP4, MOV, WebM, MKV, AVI.
Size As a file, up to 20 MB. By URL, up to 100 MB; the download must finish within 60 seconds.
fps Frames checked per second of video: 0.5 to 10. Default 1.
Frames At most 300 frames per video: 5 minutes at fps: 1, 30 seconds at fps: 10. A longer video, or one that takes more than 80 seconds to check, is refused with video_too_long: send it in shorter parts. If the part already read had to be paid for, it is charged (charged, at most five units).
Price detect: 1 credit. capture and censor: 2 credits. Per started 60 frames checked (the video's length times fps): a unit a minute at fps: 1. Twice that for an answer given at once (the default); the table is the async price. See Size.
tracking true follows each finding from frame to frame (see Tracking). Free. Default false.
flags The flags to check, with keys from GET /api/v1/flags. Default: every flag of the type. The models that feed none of them are not run on any frame, so the video is checked faster. See Choosing flags.
metadata Any JSON object, at most 16 KB. It comes back unchanged in the answer and in webhooks. See Metadata and actions.

A higher fps catches shorter moments but covers less of a long video. For most content 1 or 2 is enough.

Flags#

Your account's video flags are the video_moderation list of GET /api/v1/flags. They depend on your plan and can change, so they are not listed here. A flag with positions gives a box and the moment in the video for each finding. See Flags.

The result#

{
  "id": 1060,
  "type": "video_moderation",
  "mode": "capture",
  "status": "completed",
  "flagged": true,
  "flags": [
    {
      "flag": "nudity",
      "confidence": 0.91,
      "detections": [
        { "label": "exposed_breasts", "confidence": 0.91, "bbox": [212, 140, 388, 301], "frame": 0, "t": 0 },
        { "label": "exposed_breasts", "confidence": 0.88, "bbox": [220, 150, 390, 300], "frame": 1, "t": 0.5 }
      ]
    }
  ],
  "checked": ["nudity", "explicit_nudity", "sexual_objects", "smoking"],
  "unchecked": [],
  "media": { "kind": "video", "fps": 2, "frames": 3, "width": 640, "height": 360, "durationS": 1.5, "truncated": false },
  "tookMs": 5400,
  "usage": { "charged": 4, "remaining": 26 }
}

Each detection is one finding in one sampled frame:

  • t: seconds from the start of the video. frame: the index of the sampled frame.
  • bbox: the box [x1, y1, x2, y2] in pixels of the video frame (media.width × media.height).

media describes the sampling: frames checked, the video's size and length, and truncated.

To list the moments a flag appears, group its detections by t:

from collections import defaultdict

moments = defaultdict(list)
for flag in result["flags"]:
    for d in flag.get("detections", []):
        moments[d["t"]].append(flag["flag"])
for t in sorted(moments):
    print(f"{t:6.1f}s  {', '.join(sorted(set(moments[t])))}")

Censored copy#

With "mode": "censor" you also get a copy of the video with every detection hidden, re-encoded as H.264 MP4 (censored.contentType: "video/mp4"). See Modes and censoring.

Tracking#

A model can miss an object for a frame or two: it turns, something passes in front of it, or its score dips just under the threshold. With "tracking": true, each finding is followed from frame to frame as the same object, so those frames still carry it:

  • Every detection has track, the object's number. It is the same in every frame the object appears in.
  • Detections that tracking added have tracked: true and the object's best confidence. They fill the checked frames between two sightings (gaps of up to two sampling steps, and at least a second), and the next checked frame after the last sighting. Before its first sighting an object is covered for one sampling step, at most half a second.
  • An object is followed once it has been seen in two checked frames in a row. Something seen in a single frame is reported as it is, and is not carried to other frames.
  • With "mode": "censor", the censored video hides the object on every frame, following it between the checked ones.
{ "label": "smoking", "confidence": 0.88, "bbox": [412, 188, 470, 231], "frame": 45, "t": 1.5, "track": 1, "tracked": true }

Tracking is free. Without it, results are exactly as before. How it works, and how it differs for live streams: Tracking.

Errors specific to videos#

These return 400 with "error": "invalid_input" and this message:

message Cause
input must be an http(s) URL input is not a web address.
send the video as a file or by its URL; base64 is for images only input is a data URL.
the video could not be downloaded Unreachable host, timeout (60 s), or connection error.
the video could not be downloaded (HTTP 403) The server answered with an error.
the URL does not point to a video The server did not answer with a video content type.
video/x-flv is not supported; use MP4, MOV or WebM Unsupported format.
this file type is not supported; use MP4, MOV or WebM A file sent without a type that is not a video Detectivision reads.
the file is empty The form's file has no bytes.
the video is larger than 100 MB The video at the URL is too large.
the video could not be read; it may be damaged, too large or in an unsupported format The file could not be decoded.

A video file over 20 MB gets 413 with "error": "payload_too_large" and the message the video is larger than 20 MB: send a larger one by its URL. An fps outside 0 to 10 is refused with 400 Invalid moderation request. Other errors: Errors.