Send the image one of three ways: as a file, by its URL, or in base64. Detectivision checks it and does not store it; an async request's image waits only until its check runs.
Note
Image flags judge the whole image: answers have no positions, and capture and censor return what detect returns, at the same price.
Send the image#
As a file#
Send a form (multipart/form-data) with the image in the field file and the other fields beside it. Let your HTTP client write the form's Content-Type: it adds the boundary.
curl https://api.detectivision.ai/api/v1/moderation \
-H "Api-Key: $DETECTIVISION_API_KEY" \
-F "type=image_moderation" \
-F "mode=capture" \
-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", "mode": "capture"},
files={"file": f},
)
print(r.json())import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("type", "image_moderation");
form.append("mode", "capture");
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,
});
console.log(await res.json());A service that already holds the image needs no URL for it: a bot that receives a user's photo, for example from Telegram, can send the file as it is.
By URL#
Send the address of the image as input. Detectivision downloads it, checks it and forgets it.
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", "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.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(await res.json());In base64#
Send the image as a data URL in input: data:image/jpeg;base64, and the image's base64. Use it when your client sends only JSON: base64 makes the request a third larger than the image.
printf '{"type": "image_moderation", "input": "data:image/jpeg;base64,%s"}' "$(base64 < photo.jpg | tr -d '\n')" > body.json
curl https://api.detectivision.ai/api/v1/moderation \
-H "Api-Key: $DETECTIVISION_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @body.jsonimport base64, os, requests
with open("photo.jpg", "rb") as f:
image = base64.b64encode(f.read()).decode()
r = requests.post(
"https://api.detectivision.ai/api/v1/moderation",
headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
json={"type": "image_moderation", "input": f"data:image/jpeg;base64,{image}"},
)
print(r.json())import { readFile } from "node:fs/promises";
const image = (await readFile("photo.jpg")).toString("base64");
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: `data:image/jpeg;base64,${image}` }),
});
console.log(await res.json());The answer is the same whichever way the image comes. A file or a base64 image is checked and not stored; only its name is kept with the request (upload: photo.jpg, or upload: base64 image). An async one is kept only until its check runs, at most 24 hours.
Requirements#
| File | The field file of a multipart/form-data body, with the other fields beside it (see Form fields). A file sent as application/octet-stream or without a type of its own is recognised by its first bytes. |
| URL | An http:// or https:// URL, reachable from the internet without signing in. Signed URLs (for example from S3) work while they are valid. The download must finish within 10 seconds, and the server must answer with an image/… content type. |
| Base64 | A data URL in input: data:image/jpeg;base64,…, or image/png, image/webp, image/gif, image/bmp. |
| Formats | JPEG, PNG, WebP, BMP, GIF. |
| Size | Up to 10 MB however it is sent, 40 megapixels and 10,000 pixels on a side. In base64 a 10 MB image is about 13.3 MB of text; a JSON body may be up to 14 MB. |
| Price | 1 credit, in every mode. Twice that for an answer given at once (the default); the table is the async price. capture and censor cost one credit more only for flags with positions, which image flags do not have. See Prices. |
| Flags | Every flag of the type by default. To check some only, name them in flags, with keys from GET /api/v1/flags: the others are not checked, and the models that feed none of yours are not run, so the answer comes faster. See Choosing flags. |
| Metadata | Any JSON object, at most 16 KB, in metadata. It comes back unchanged in the answer and in webhooks. See Metadata and actions. |
Detectivision downloads images with the user agent DetectivisionBot/1.0 (+https://detectivision.ai). If your storage blocks unknown clients, allow this one.
Form fields#
A form takes the fields of the JSON body, as text: type (required), mode, censorStyle, flags (keys separated by commas, or the field once for each), fps, tracking and async (true or false), and metadata (the JSON object as text). The image goes in file; a form has no input. An empty field counts as not sent.
Flags#
Your account's image flags are the image_moderation list of GET /api/v1/flags. They depend on your plan and can change, so they are not listed here. Each of them judges the whole image; see Positions.
The result#
An example answer: a photo of a product with a phone number written on it.
{
"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 }
}flagslists the flags raised, each with itsconfidence, from 0 to 1. Base decisions onflag.- In
captureandcensormode each flag also hasdetections. They hold alabeland aconfidenceand no position, so they tell you no more thandetect. - With
"mode": "detect"the answer has only the flags and their confidence, no detections.
In the example, the phone number raised scam. The flag covers fraud and also contact details written on the picture: a phone number (in digits or written out in words), a WhatsApp, Telegram, Snapchat or Instagram handle, an e-mail address, an IBAN or a crypto wallet. Fake giveaways or prizes, phishing QR codes or links, fake payment or bank screens, and get-rich-quick or investment promises count too. A price, a brand or product name, a shop sign without a way to reach someone, the platform's own watermark and ordinary text do not.
Boxes#
Image flags judge the whole image, so answers do not have these fields. This is reference for flags with positions: a detection of a flag with positions has:
bbox: the box[x1, y1, x2, y2]around the finding, in pixels of the original image (top-left corner, bottom-right corner). To draw it on a resized copy, scale by the ratio of the sizes.polygon(when the model provides it): the outline as[x, y]points, in the same pixels.
Censored copy#
With "mode": "censor" a copy hides what flags with positions found (censorStyle: blur, the default, pixelate or box). Image flags judge the whole image, so no copy is made and the answer has no censored field. See Modes and censoring.
Errors specific to images#
These return 400 with "error": "invalid_input" and this message:
message |
Cause |
|---|---|
input must be an http(s) URL |
input is not a web address or a data URL. |
the image could not be downloaded |
Unreachable host, timeout, or connection error. |
the image could not be downloaded (HTTP 404) |
The server answered with an error (the status is included). |
the URL does not point to an image |
The server did not answer with an image content type. |
image/svg+xml is not supported; use JPEG, PNG, WebP, BMP or GIF |
Unsupported format (the type is included). |
this file type is not supported; use JPEG, PNG, WebP, BMP or GIF |
A file sent without a type that is not an image Detectivision reads. |
the image is larger than 10 MB |
The image at the URL is too large. |
the file is empty |
The form's file has no bytes. |
the image is not valid base64 |
The data URL's data is not base64. |
a data URL must be base64: data:image/png;base64,… |
The data URL is not a base64 one. |
the image is empty |
The data URL has no data. |
the image could not be read; it may be damaged or too large |
Corrupt file, or more than 40 megapixels. |
A file or a base64 image over 10 MB gets 413 with "error": "payload_too_large" and the message the image is larger than 10 MB. A form without its file, or with input beside it, gets 400 invalid_request, with the problem in details.
Nothing is charged for these. Other errors: Errors.