1. Get an API key#
- Sign in or create an account.
- Open Dashboard → API Keys and select Create API Key.
- Give it a name and choose Write permission (a key that can only read cannot run checks).
- 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 }
}flaggedis the verdict:truewhen at least one flag was raised.flagslists them.confidencegoes from 0 to 1. Every image flag judges the whole image, so a detection has no box.checkedare the flags that were looked for. A flag incheckedbut not inflagswas not found.usage.chargedis what this check cost;usage.remainingis 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 inunchecked. 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-Afterheader 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#
- Moderate text, images, video and live streams.
- Modes and censoring: what each mode returns and costs.
- Async requests: content that can wait costs half, and its result comes by webhook.
- API Reference: every field of the request and the result.