Concepts / Responses
Concepts

Responses

Every field of a Detectivision moderation result explained, the same object for every type: flags, confidence, status, usage and your metadata.

On this page

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), in checked but not flags (looked for, not found), or in unchecked (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 flags or checked: look for the flags you act on.
  • Check status before 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"