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: trueand 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.