API Reference / Read a request back
API Reference

Read a request back

GET/api/v1/moderation/{id}

The request's stored answer, your metadata, whether anyone acted on it (state) and the actions taken. Any key that is not restricted can read.

Path parameters#

Parameter Type Description
id required integer The request's id.

Responses#

200#

The request.

  • id integer required

  • 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).

  • createdAt integer required

    When it was made, in Unix seconds.

  • metadata object

    Your metadata from the request, when you sent one.

  • state string required

    One of: pending, actioned. pending until the first action is taken.

  • actions array of ActionTaken required

    The actions taken, oldest first.

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

  • status string

    One of: queued, processing, completed, partial, unavailable. queued or processing: an async request waiting or being checked (a live session in progress is processing too). completed or partial: as in the moderation answer. unavailable: the check could not run (see error).

  • flagged boolean

    true when at least one flag was raised.

  • flags array of FlagResult

    The flags raised, empty when the content is clean.

  • checked array of string

    Flags that were checked.

  • unchecked array of string

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

  • message string

    Partial results and checks that could not run: what happened.

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

  • tookMs integer

    Processing time in milliseconds.

  • usage object

    What the request was charged.

  • charged integer

    Checks that could not run: 0, nothing was charged.

  • retryAfter integer or null

    Seconds to wait (also sent as the Retry-After header); null for not_available_yet.

  • statusUrl string

  • live object (LiveSession) or object

    Live streams: a session's entry carries the session as it ended; a moment carries the session it belongs to and when.

  • error any

    A check that could not run: temporarily_unavailable or not_available_yet (see Errors); for an async request that failed, any error code.

actions[] (ActionTaken)

  • id integer required

  • key string required

  • label string required

  • by object (Actor) required

    Who took an action.

  • note string or null required

  • at integer required

    When, in Unix seconds.

by (Actor)

  • type string required

    One of: user, api. user: someone in the dashboard; api: a call with an API key.

  • name string required

    The person's name, or the API key's label.

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

usage

  • charged integer required

    Credits taken by the request.

401#

Missing, unknown, revoked or expired API key, or the account is not active.

{
  "error": "unauthorized",
  "message": "The API key is not valid."
}

404#

No such request for this account.

{
  "error": "not_found",
  "message": "No such request."
}

429#

Too many requests in a minute. Wait Retry-After seconds. See Rate limits.

Header Retry-After: Seconds to wait.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again in a minute."
}

Request

curl -X GET https://api.detectivision.ai/api/v1/moderation/{id} \
  -H "Api-Key: $DETECTIVISION_API_KEY"
import os, requests

r = requests.get(
    "https://api.detectivision.ai/api/v1/moderation/{id}",
    headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
)
print(r.status_code, r.json())
const res = await fetch("https://api.detectivision.ai/api/v1/moderation/{id}", {
  method: "GET",
  headers: {
    "Api-Key": process.env.DETECTIVISION_API_KEY,
  },
});
console.log(res.status, await res.json());