API Reference / Moderate content
API Reference

Moderate content

POST/api/v1/moderation

Checks 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#

  • type string required

    One of: text_moderation, image_moderation, video_moderation, audio_moderation, live_stream_moderation. The kind of content to check. live_stream_moderation is done with live sessions (400 here).

  • input string required

    Text: 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,… (or image/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).

  • mode string

    One of: detect, capture, censor. detect: flags and confidence only. capture: also detections, 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".

  • fps number

    Videos: frames checked per second of video, 0.5 to 10. Default: 1. From 0.5 to 10.

  • censorStyle string

    One of: blur, pixelate, box. How censor hides 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".

  • flags array of string

    The 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: capture and censor cost what detect costs 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.

  • tracking boolean

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

  • metadata object

    Your own JSON (an object of at most 16 KB), sent back unchanged in answers and webhooks. See /docs/actions.

  • async boolean

    No answer needed now: the API answers 202 with the request's id at once and checks it later, at the price table. The result comes as a webhook (moderation.completed, or moderation.failed) and from GET /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 gets 429 too_many_requests with Retry-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.

  • type string required

    One of: text_moderation, image_moderation, video_moderation, audio_moderation, live_stream_moderation. The kind of content to check. live_stream_moderation is done with live sessions (400 here).

  • file file required

    The 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 is application/octet-stream or missing. A text goes as input in a JSON body, and a video over 20 MB by its URL (up to 100 MB).

  • mode string

    One of: detect, capture, censor. detect: flags and confidence only. capture: also detections, 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".

  • fps number

    Videos: frames checked per second of video, 0.5 to 10. Default: 1. From 0.5 to 10.

  • censorStyle string

    One of: blur, pixelate, box. How censor hides 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".

  • flags array of string

    The 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.

  • tracking boolean

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

  • metadata string

    Your own JSON object as text, at most 16 KB, sent back unchanged in answers and webhooks. See /docs/actions.

  • async boolean

    true: the API answers 202 with the request's id at 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).

  • id integer required

    The request's id. Read the request back with it, and quote it to support.

  • type string required

    One of: text_moderation, image_moderation, video_moderation, audio_moderation, live_stream_moderation. The kind of content to check. live_stream_moderation is done with live sessions (400 here).

  • mode string required

    One of: detect, capture, censor. detect: flags and confidence only. capture: also detections, 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.

  • status string required

    One of: completed, partial. partial: some flags could not be checked (listed in unchecked). A partial result is not charged.

  • flagged boolean required

    true when at least one flag was raised.

  • flags array of FlagResult required

    The flags raised, empty when the content is clean.

  • checked array of string required

    Flags that were checked.

  • unchecked array of string required

    Flags that could not be checked. A flag missing here and from flags was checked and not found.

  • message string

    Partial results: Some checks are unavailable.

  • media object (Media)

    Videos: how the video was sampled.

  • tracking boolean

    Videos asked with tracking: always true. Detections carry track, and the ones tracking added tracked.

  • censoredText string

    Text 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.

  • censored object (Censored)

    Images and videos with mode: "censor", when a flag with positions found something: either the copy (url, contentType, regions) or error when it could not be kept. Text and image flags have no positions, so their answers do not have it.

  • transcript object

    Audio: what was said (see Responses).

  • tookMs integer required

    Processing time in milliseconds.

  • usage object (Usage) required

    What this request cost, and what is left.

  • metadata object

    Your metadata from the request, unchanged, when you sent one.

flags[] (FlagResult)

  • flag string required

    The flag's key, one of those GET /api/v1/flags lists. See Flags.

  • confidence number required

    The highest confidence among the flag's detections. From 0 to 1.

  • detections array of Detection

    The flag's findings, strongest first. Not present in detect mode. For text and image flags they have no position.

detections[] (Detection)

  • label string required

    The model's own label for the finding (informational; may change). Use flag for decisions.

  • confidence number required

    How sure the model is. From 0 to 1.

  • bbox array of number

    Images and videos, for a flag with positions: the box [x1, y1, x2, y2] in pixels of the original image or video frame.

  • polygon array of array of number

    Images and videos, when the model outlines the finding: its outline as [x, y] points in original pixels.

  • t number

    Videos, for a flag with positions: seconds from the start of the video.

  • frame integer

    Videos, for a flag with positions: the index of the sampled frame.

  • track integer

    With tracking: the object this finding belongs to. The same object keeps the same number across frames. From 1.

  • tracked boolean

    With tracking: true when a model missed the object in this frame and tracking carried it over. Its confidence is the object's best.

  • start number

    Text: start of the span, a Unicode code point index (inclusive). Audio: seconds.

  • end number

    Text: end of the span, a Unicode code point index (exclusive). Audio: seconds.

  • text string

    Audio: the words.

media (Media)

  • kind string required

    One of: video. Always video.

  • fps number required

    Frames checked per second.

  • frames integer required

    Frames checked.

  • width integer required

    Video width in pixels.

  • height integer required

    Video height in pixels.

  • durationS number

    Video length in seconds, when known.

  • truncated boolean required

    true when checking stopped before the end (at most 300 frames or 80 seconds of processing).

censored (Censored)

  • url string

    Where to download the copy (with your API key).

  • contentType string

    One of: image/jpeg, video/mp4. image/jpeg for images, video/mp4 (H.264) for videos.

  • regions integer

    How many regions were hidden.

  • error string

    Why there is no copy. The request is still charged: run it again to get one.

usage (Usage)

  • charged integer required

    Credits 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.

  • remaining integer required

    The 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.

  • id integer required

    The request's id: read it back with GET /api/v1/moderation/{id}.

  • type string required

    One of: text_moderation, image_moderation, video_moderation, audio_moderation, live_stream_moderation. The kind of content to check. live_stream_moderation is done with live sessions (400 here).

  • status string required

    One of: queued.

  • metadata object

    Your 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"
  }
}