Getting started / Quickstart
Getting started

Quickstart

Get started with the Detectivision content moderation API: create an API key, run your first image moderation check and read its result in minutes.

On this page

1. Get an API key#

  1. Sign in or create an account.
  2. Open Dashboard → API Keys and select Create API Key.
  3. Give it a name and choose Write permission (a key that can only read cannot run checks).
  4. Copy the key. It is shown once: after this only its first and last characters are visible.

Keep the key on your server, for example in an environment variable:

export DETECTIVISION_API_KEY="3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c0d"

Warning

Never put an API key in a web page or a mobile app: anyone could read it and spend your credits. Call Detectivision from your backend. Browsers are blocked from calling the API directly.

Your account also needs credits for the type you check. See Dashboard → Quota for your balance.

2. Check an image#

Send an image file. The answer lists the flags it raised, each with its confidence.

curl https://api.detectivision.ai/api/v1/moderation \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -F "type=image_moderation" \
  -F "file=@photo.jpg"
import os, requests

with open("photo.jpg", "rb") as f:
    r = requests.post(
        "https://api.detectivision.ai/api/v1/moderation",
        headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
        data={"type": "image_moderation"},
        files={"file": f},
        timeout=30,
    )
r.raise_for_status()
result = r.json()
print(result["flagged"], [f["flag"] for f in result["flags"]])
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("type", "image_moderation");
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");

const res = await fetch("https://api.detectivision.ai/api/v1/moderation", {
  method: "POST",
  headers: { "Api-Key": process.env.DETECTIVISION_API_KEY },
  body: form,
});
if (!res.ok) throw new Error(`Detectivision: ${res.status} ${await res.text()}`);
const result = await res.json();
console.log(result.flagged, result.flags.map((f) => f.flag));

An image that is already online can go by its address instead, in a JSON body:

curl 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"}'
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"},
    timeout=30,
)
r.raise_for_status()
result = r.json()
print(result["flagged"], [f["flag"] for f in result["flags"]])
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" }),
});
if (!res.ok) throw new Error(`Detectivision: ${res.status} ${await res.text()}`);
const result = await res.json();
console.log(result.flagged, result.flags.map((f) => f.flag));

A JSON body can also carry the image itself, in base64: "input": "data:image/jpeg;base64,…". Image moderation shows the three ways side by side. The image is checked and not stored.

3. Read the result#

An example answer:

{
  "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 }
}
  • flagged is the verdict: true when at least one flag was raised.
  • flags lists them. confidence goes from 0 to 1. Every image flag judges the whole image, so a detection has no box.
  • checked are the flags that were looked for. A flag in checked but not in flags was not found.
  • usage.charged is what this check cost; usage.remaining is what is left for images.

Decide with the flags, for example:

BLOCK = {"sexual", "violence"}
raised = {f["flag"] for f in result["flags"]}
if raised & BLOCK:
    reject_upload()

4. Handle the other answers#

  • status: "partial": some flags could not be checked right now; they are listed in unchecked. A partial result is free. Treat those flags as unknown, and retry if you need them.
  • HTTP 503: checks are temporarily unavailable. Wait the seconds in the Retry-After header and retry. Nothing is charged.
  • HTTP 400: the request or its input cannot be used (for example the file is not an image, or the URL does not point to one), or the account has no credits left for the type. The body says which.
  • HTTP 413: the file is too large: an image may be up to 10 MB, a video up to 20 MB (a larger video goes by its URL, up to 100 MB).

See Errors for every case, and a retry example.

Next steps#