/api/v1/moderationChecks one piece of content: text (sent as-is); an image or a video, as the file itself or by URL; an image also in base64; or a recording, as the file itself or by URL. Returns the flags it raised and their confidence. Text and image flags judge the whole text or image: answers have no positions, and capture and censor return what detect returns, at the same price. Only a completed result is charged.
Request body#
Two ways to send it. As JSON (application/json): input is the text, the media's http(s) URL, or an image as a base64 data URL. As a form (multipart/form-data): file is the image or the video itself, and the other fields go beside it as text. A file or a base64 image is checked and not stored; an async one waits in storage only until its check runs, at most 24 hours.
application/json#
-
typestring requiredOne of:
text_moderation,image_moderation,video_moderation,audio_moderation,live_stream_moderation. The kind of content to check.live_stream_moderationis done with live sessions (400 here). -
inputstring requiredText: the text itself (at most 10,000 characters, as Unicode code points; priced per started 2,500). Image, video or audio: an http(s) URL our servers can download (an image up to 10 MB, a video up to 100 MB). An image can also come in base64, as a data URL:
data:image/jpeg;base64,…(orimage/png,image/webp,image/gif,image/bmp), up to 10 MB of image; the JSON body may then be up to 14 MB. To send an image or a video file itself, send a form instead (multipart/form-data, ModerationUpload). -
modestringOne of:
detect,capture,censor.detect: flags and confidence only.capture: alsodetections, which say where each flag was found for flags with positions.censor: also a censored copy of what flags with positions found. Text and image flags have no positions, so for them all three return the flags and their confidence, at the same price. Default:"capture". -
fpsnumberVideos: frames checked per second of video, 0.5 to 10. Default:
1. From 0.5 to 10. -
censorStylestringOne of:
blur,pixelate,box. Howcensorhides what flags with positions found in images and videos. Text and image flags have no positions, so no copy is made for them. Default:"blur". -
flagsarray of stringThe flags to check, with keys from
GET /api/v1/flags. Only these are checked and reported; models that feed none of them are not run, so the answer comes faster. Fewer flags never cost more:captureandcensorcost whatdetectcosts when none of them is found by a model that says where. Leave it out to check every flag of the type. A flag the type does not check is refused (400). See Flags. -
trackingbooleanVideos: follow each finding from frame to frame. The checked frames where a model misses it between two sightings (or just after the last, or just before the first) still carry it, marked
tracked, and a censored video hides it on every frame. An object seen in a single frame is not carried. Free. Default:false. -
metadataobjectYour own JSON (an object of at most 16 KB), sent back unchanged in answers and webhooks. See /docs/actions.
-
asyncbooleanNo answer needed now: the API answers
202with the request'sidat once and checks it later, at the price table. The result comes as a webhook (moderation.completed, ormoderation.failed) and fromGET /api/v1/moderation/{id}. An answer given at once costs twice the table. Text, URLs, files and base64 images: a file waits in storage only until its check runs, at most 24 hours. An account can have at most 50 async checks waiting; one more gets429too_many_requestswithRetry-After: 60. See Async requests. Default:false.
multipart/form-data#
The same request as a form: the image or the video itself in file, and the other fields as text beside it. Booleans are true or false; metadata is your JSON object as text. An empty field counts as not sent.
-
typestring requiredOne of:
text_moderation,image_moderation,video_moderation,audio_moderation,live_stream_moderation. The kind of content to check.live_stream_moderationis done with live sessions (400 here). -
filefile requiredThe image (JPEG, PNG, WebP, BMP or GIF, up to 10 MB) the video (MP4, MOV, WebM, MKV or AVI) or the recording, up to 20 MB, itself. Its type comes from the part's
Content-Type, or from its first bytes when that isapplication/octet-streamor missing. A text goes asinputin a JSON body, and a video over 20 MB by its URL (up to 100 MB). -
modestringOne of:
detect,capture,censor.detect: flags and confidence only.capture: alsodetections, which say where each flag was found for flags with positions.censor: also a censored copy of what flags with positions found. Text and image flags have no positions, so for them all three return the flags and their confidence, at the same price. Default:"capture". -
fpsnumberVideos: frames checked per second of video, 0.5 to 10. Default:
1. From 0.5 to 10. -
censorStylestringOne of:
blur,pixelate,box. Howcensorhides what flags with positions found in images and videos. Text and image flags have no positions, so no copy is made for them. Default:"blur". -
flagsarray of stringThe flags to check, with keys from
GET /api/v1/flags: the field once for each key, or one field with the keys separated by commas (nudity,smoking). Leave it out to check every flag of the type. -
trackingbooleanVideos: follow each finding from frame to frame. The checked frames where a model misses it between two sightings (or just after the last, or just before the first) still carry it, marked
tracked, and a censored video hides it on every frame. An object seen in a single frame is not carried. Free. Default:false. -
metadatastringYour own JSON object as text, at most 16 KB, sent back unchanged in answers and webhooks. See /docs/actions.
-
asyncbooleantrue: the API answers202with the request'sidat once and checks the file later, at the price table. The file waits in storage only until its check runs, at most 24 hours. See Async requests. Default:false.
Responses#
200#
The content was checked. status is completed, or partial when some checks could not run (a partial result is free).
-
idinteger requiredThe request's id. Read the request back with it, and quote it to support.
-
typestring requiredOne of:
text_moderation,image_moderation,video_moderation,audio_moderation,live_stream_moderation. The kind of content to check.live_stream_moderationis done with live sessions (400 here). -
modestring requiredOne of:
detect,capture,censor.detect: flags and confidence only.capture: alsodetections, which say where each flag was found for flags with positions.censor: also a censored copy of what flags with positions found. Text and image flags have no positions, so for them all three return the flags and their confidence, at the same price. -
statusstring requiredOne of:
completed,partial.partial: some flags could not be checked (listed inunchecked). A partial result is not charged. -
flaggedboolean requiredtruewhen at least one flag was raised. -
flagsarray of FlagResult requiredThe flags raised, empty when the content is clean.
-
checkedarray of string requiredFlags that were checked.
-
uncheckedarray of string requiredFlags that could not be checked. A flag missing here and from
flagswas checked and not found. -
messagestringPartial results:
Some checks are unavailable. -
mediaobject (Media)Videos: how the video was sampled.
-
trackingbooleanVideos asked with
tracking: alwaystrue. Detections carrytrack, and the ones tracking addedtracked. -
censoredTextstringText with
mode: "censor": the text with the flagged spans masked by*(same length). Only flags with positions are masked, and text flags have none, so it is the text as you sent it. -
censoredobject (Censored)Images and videos with
mode: "censor", when a flag with positions found something: either the copy (url,contentType,regions) orerrorwhen it could not be kept. Text and image flags have no positions, so their answers do not have it. -
transcriptobjectAudio: what was said (see Responses).
-
tookMsinteger requiredProcessing time in milliseconds.
-
usageobject (Usage) requiredWhat this request cost, and what is left.
-
metadataobjectYour
metadatafrom the request, unchanged, when you sent one.
flags[] (FlagResult)
-
flagstring requiredThe flag's key, one of those
GET /api/v1/flagslists. See Flags. -
confidencenumber requiredThe highest confidence among the flag's detections. From 0 to 1.
-
detectionsarray of DetectionThe flag's findings, strongest first. Not present in
detectmode. For text and image flags they have no position.
detections[] (Detection)
-
labelstring requiredThe model's own label for the finding (informational; may change). Use
flagfor decisions. -
confidencenumber requiredHow sure the model is. From 0 to 1.
-
bboxarray of numberImages and videos, for a flag with positions: the box
[x1, y1, x2, y2]in pixels of the original image or video frame. -
polygonarray of array of numberImages and videos, when the model outlines the finding: its outline as
[x, y]points in original pixels. -
tnumberVideos, for a flag with positions: seconds from the start of the video.
-
frameintegerVideos, for a flag with positions: the index of the sampled frame.
-
trackintegerWith
tracking: the object this finding belongs to. The same object keeps the same number across frames. From 1. -
trackedbooleanWith
tracking:truewhen a model missed the object in this frame and tracking carried it over. Its confidence is the object's best. -
startnumberText: start of the span, a Unicode code point index (inclusive). Audio: seconds.
-
endnumberText: end of the span, a Unicode code point index (exclusive). Audio: seconds.
-
textstringAudio: the words.
media (Media)
-
kindstring requiredOne of:
video. Alwaysvideo. -
fpsnumber requiredFrames checked per second.
-
framesinteger requiredFrames checked.
-
widthinteger requiredVideo width in pixels.
-
heightinteger requiredVideo height in pixels.
-
durationSnumberVideo length in seconds, when known.
-
truncatedboolean requiredtruewhen checking stopped before the end (at most 300 frames or 80 seconds of processing).
censored (Censored)
-
urlstringWhere to download the copy (with your API key).
-
contentTypestringOne of:
image/jpeg,video/mp4.image/jpegfor images,video/mp4(H.264) for videos. -
regionsintegerHow many regions were hidden.
-
errorstringWhy there is no copy. The request is still charged: run it again to get one.
usage (Usage)
-
chargedinteger requiredCredits taken by this request (0 for a partial result): the price per unit times the units, a text's per 2,500 characters and a video's per 60 frames checked.
-
remaininginteger requiredThe account's credits left for this moderation type after the request. Below zero after a video that cost more than was left: checks of the type are then refused until credits are added.
202#
async: true: accepted, to be checked later. Nothing is charged yet: the check is charged the table price when it runs.
Header Location: Where to read the request back.
-
idinteger requiredThe request's id: read it back with
GET /api/v1/moderation/{id}. -
typestring requiredOne of:
text_moderation,image_moderation,video_moderation,audio_moderation,live_stream_moderation. The kind of content to check.live_stream_moderationis done with live sessions (400 here). -
statusstring requiredOne of:
queued. -
metadataobjectYour
metadata, as sent.
400#
The request is invalid, the input cannot be used, or there are not enough credits.
{
"error": "invalid_input",
"message": "the URL does not point to an image"
}{
"error": "invalid_request",
"message": "Invalid moderation request",
"details": [
{
"code": "invalid_value",
"path": [
"type"
],
"message": "Invalid moderation type"
}
]
}{
"error": "insufficient_quota",
"message": "Not enough credits for image_moderation."
}{
"error": "invalid_flags",
"message": "image_moderation does not check insult. Flags it checks: hate, scam, sexual, violence."
}401#
Missing, unknown, revoked or expired API key, or the account is not active.
{
"error": "unauthorized",
"message": "The API key is not valid."
}403#
The key may not do this: a read key on a write endpoint, or a restricted key.
{
"error": "forbidden",
"message": "This API key does not have write permission"
}413#
Too large: a moderation request's file (an image over 10 MB, a video over 20 MB) or base64 image (over 10 MB), its JSON body over 14 MB, or any other JSON body over 100 KB.
{
"error": "payload_too_large",
"message": "Request body too large"
}429#
Too many requests in a minute (see Rate limits), or, with async: true, 50 checks of the account already waiting (see Async requests). Nothing is queued or charged. Wait Retry-After seconds.
Header Retry-After: Seconds to wait.
{
"error": "too_many_requests",
"message": "Too many requests. Try again in a minute."
}{
"error": "too_many_requests",
"message": "Too many checks are waiting: at most 50 per account. Send more once some have run."
}503#
No check can run right now (temporarily_unavailable, with a Retry-After header) or the moderation type cannot be served right now (not_available_yet). Nothing is charged.
Header Retry-After: Seconds to wait before retrying (temporarily_unavailable only).
{
"error": "temporarily_unavailable",
"message": "Image moderation is temporarily unavailable.",
"status": "unavailable",
"type": "image_moderation",
"charged": 0,
"retryAfter": 60,
"statusUrl": "https://api.detectivision.ai/api/v1/status"
}Request
curl -X POST https://api.detectivision.ai/api/v1/moderation \
-H "Api-Key: $DETECTIVISION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "image_moderation",
"input": "https://example.com/photo.jpg",
"mode": "capture"
}'import os, requests
r = requests.post(
"https://api.detectivision.ai/api/v1/moderation",
headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
json={
"type": "image_moderation",
"input": "https://example.com/photo.jpg",
"mode": "capture"
},
)
print(r.status_code, 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": "image_moderation",
"input": "https://example.com/photo.jpg",
"mode": "capture"
}),
});
console.log(res.status, await res.json());Response 200
{
"id": 1042,
"type": "image_moderation",
"mode": "capture",
"status": "completed",
"flagged": true,
"flags": [
{
"flag": "scam",
"confidence": 0.94,
"detections": [
{
"label": "scam",
"confidence": 0.94
}
]
}
],
"checked": [
"hate",
"scam",
"sexual",
"violence"
],
"unchecked": [],
"tookMs": 412,
"usage": {
"charged": 2,
"remaining": 28
}
}Response 202
{
"id": 1043,
"type": "image_moderation",
"status": "queued",
"metadata": {
"commentId": "c_981"
}
}