Every moderation check returns the same object, whatever the type. Fields that only apply to some types or modes are left out when they do not apply. An example:
{
"id": 1042,
"type": "image_moderation",
"mode": "capture",
"status": "completed",
"flagged": true,
"flags": [
{ "flag": "sexual", "confidence": 0.91, "detections": [{ "label": "sexual", "confidence": 0.91 }] }
],
"checked": ["hate", "scam", "sexual", "violence"],
"unchecked": [],
"tookMs": 412,
"usage": { "charged": 2, "remaining": 28 }
}Note
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.
Fields#
| Field | Type | Present | Meaning |
|---|---|---|---|
id |
integer | always | The request's id. Read the request back with it; quote it to support. |
type |
string | always | The moderation type you sent. |
mode |
string | always | detect, capture or censor. |
status |
string | always | completed or partial. See below. |
flagged |
boolean | always | true when at least one flag was raised. |
flags |
array | always | The flags raised; [] when clean. |
checked |
string[] | always | The flags that were looked for. |
unchecked |
string[] | always | The flags that could not be looked for; [] when completed. |
message |
string | partial results | Some checks are unavailable. |
media |
object | videos | How the video was sampled. |
transcript |
object | audio | What was said: the language, the length and the text; with capture or censor, each sentence with its seconds and flags. See below. |
censored |
object | images and videos in censor mode, when a flag with positions found something |
The censored copy. Text and image flags have no positions, so their answers do not have it. See Modes and censoring. |
censoredText |
string | text in censor mode |
The text with the words that flags with positions found masked. Text flags have no positions, so it is your text unchanged. |
tookMs |
integer | always | Processing time in milliseconds. |
usage.charged |
integer | always | Credits this check cost: its price when completed, 0 when partial. |
usage.remaining |
integer | always | Credits left for this moderation type. Below zero after a video that cost more than was left. |
metadata |
object | when sent | Your own JSON from the request, unchanged. See Metadata and actions. |
A flag#
| Field | Meaning |
|---|---|
flag |
The flag key, one of those GET /api/v1/flags lists. |
confidence |
0 to 1: the strongest finding. |
detections |
The findings (not in detect mode), strongest first. |
A detection#
A text or image detection has label and confidence only. The position fields below come from flags with positions, which video and live stream flags have.
| Field | Type | When | Meaning |
|---|---|---|---|
label |
string | always | The model's own name for the finding. Informational; may change. |
confidence |
number | always | 0 to 1. |
bbox |
number[4] | images, videos, streams, for flags with positions | [x1, y1, x2, y2]: top-left and bottom-right corners in pixels of the original image or frame. |
polygon |
number[][] | images, videos, when available | The outline as [x, y] points in the same pixels. |
t |
number | videos, for flags with positions | Seconds from the start of the video. |
frame |
integer | videos, for flags with positions | Index of the sampled frame. |
start, end |
integer | text, for flags with positions | The span in the text, as Unicode code point indexes (end exclusive). |
start, end |
number | audio | When it was said: seconds from the beginning of the recording. |
text |
string | audio | What was said there: the words a model marked, or the sentence the finding is in. |
media (videos)#
| Field | Meaning |
|---|---|
kind |
video. |
fps |
Frames checked per second. |
frames |
Frames checked. |
width, height |
The video's size in pixels. |
durationS |
Its length in seconds, when known. |
truncated |
Always false: a video that cannot be checked to its end is refused with video_too_long. |
transcript (audio)#
A recording's speech is transcribed, then checked for the flags text is checked for. Each finding comes with the seconds it was said in, and the answer carries what was said:
{
"language": "tr",
"durationS": 6,
"text": "Merhaba, nasılsınız bugün? Sen tam bir salak birisin.",
"segments": [
{ "start": 0, "end": 2, "text": "Merhaba, nasılsınız bugün?", "flags": [] },
{ "start": 2, "end": 4, "text": "Sen tam bir salak birisin.", "flags": [{ "flag": "profanity", "confidence": 0.98 }] }
]
}| Field | Meaning |
|---|---|
language |
The language heard, as an ISO 639-1 code; null when nothing was said. |
durationS |
The recording's length in seconds. |
text |
Everything said, as one text. |
segments |
With capture or censor: each sentence with its start and end in seconds, its text and the flags found in it, strongest first. |
Complete and partial results#
A check can raise flags from several models. When one of them cannot answer right now, you still get the rest:
{
"status": "partial",
"flagged": true,
"flags": [{ "flag": "sexual", "confidence": 0.91 }],
"checked": ["hate", "scam", "sexual"],
"unchecked": ["violence"],
"message": "Some checks are unavailable.",
"usage": { "charged": 0, "remaining": 30 }
}- A partial result is free (
usage.charged: 0), except a recording's: the minutes the speech model heard are charged. - A flag is never silently "clean": each flag is in
flags(raised), incheckedbut notflags(looked for, not found), or inunchecked(not looked for). - If you need the unchecked flags, retry later; the status endpoint shows when they are back.
Reading results safely#
- New fields may be added to results at any time. Ignore fields you do not know.
- Do not rely on the order of
flagsorchecked: look for the flags you act on. - Check
statusbefore treating a result without flags as clean.
def verdict(result, block):
raised = {f["flag"] for f in result["flags"]}
if raised & block:
return "block"
if set(result["unchecked"]) & block:
return "retry" # a flag you care about was not checked
return "allow"