Documentation menu

NSFW image moderation

Last updated: 2026-10-22

Analyze one image for NSFW content. The result gives the probability of each of four levels, from L1 (lowest risk) to L4 (most explicit), the most probable level, and a pass or flag verdict under the policy you choose. Submit an HTTPS image URL and retrieve the result asynchronously.

ModelEndpointPrice
generalPOST /v1/predictions1 credit per accepted task; a task that fails returns its credit

Related resources: Pricing · Credits · Task history

Request

POST https://api.nsfwcheckapi.com/v1/predictions

Header Params

Authorizationstringrequired

Bearer followed by your API key.

Example:
Bearer sk_…
Content-Typestringrequired
Allowed:
application/json
Idempotency-Keystringoptional

Recommended. 16–128 characters: letters, digits, _ or -. Reuse it only to retry an identical body; a replay returns the existing task without another charge. See Retries and idempotency.

Example:
upload-8f2c1e7a9b3d4c5e

Body Params

modelstringoptional

The model to run.

Allowed:
"general"
Default:
"general"
inputobjectrequired

The image to check. Holds image.

input.imagestringrequired

Public HTTPS URL of one static JPEG, PNG or WebP image. The URL is at most 4,096 bytes; the image is at most 20 MiB, 8,192 px per side and 40 million px in total.

Example:
"https://images.example.com/photo.jpg"
policyobjectoptional

How the result is judged. Holds sensitivity.

Default:
{"sensitivity": "standard"}
policy.sensitivitystringoptional

"standard" flags L3 and L4; "strict" flags L2, L3 and L4. It changes only output.is_nsfw, never the probabilities or the level.

Allowed:
"standard"
"strict"
Default:
"standard"
Example:
"strict"

Fields not listed here, null values and duplicate keys are rejected with 400 invalid_request.

Image URL rules

  • https:// only, with no user name or password and no #fragment.
  • Not a local or private address; redirect targets are checked too.
  • GIF, APNG and animated WebP are not supported.
  • The URL must stay reachable until the task is final. For a signed URL, the whole query string is part of the input.

URL problems found at submission return 422 invalid_image_url and create no task. Problems found while downloading or decoding the image end the task as failed with error code invalid_image, and its credit is returned.

Responses

StatusMeaning
201Task accepted with "status": "waiting". The Location header is the URL to query. Image problems found later appear in the task's error.
200Idempotent replay: the original task in its current state, with the header Idempotent-Replayed: true. No new task and no extra charge.
400 401 402 409 413 422 429 503The request was not accepted and nothing is charged. See Errors.

Response fields

FieldTypeNotes
idstringTask ID (a UUID).
modelstring"general"
statusstring"waiting", "processing", "succeeded" or "failed". A new task is "waiting".
policy.sensitivitystring"standard" or "strict", as submitted.
model_versionstring or nullVersion of the model that produced the result, for example "general-2026-08"; null until then.
outputobject or nullThe result; null until status is "succeeded".
errorobject or nullnull unless status is "failed".
created_atstringWhen the task was accepted.
started_atstring or nullWhen processing started.
completed_atstring or nullWhen the task reached a final status.
urls.getstringURL that returns this task.

Output object

Present when status is "succeeded".

FieldTypeNotes
output.levelstringThe most probable level: "L1", "L2", "L3" or "L4". On a tie the higher level wins.
output.probabilitiesobjectProbability of each level: keys L1–L4, numbers between 0 and 1.
output.is_nsfwbooleantrue when output.level is flagged under the task's policy.

Error object

Present when status is "failed". The credit of a failed task is returned.

error.codeMeaning
invalid_imageThe image could not be downloaded or decoded, or is not a supported format or size.
processing_timeoutThe task did not start within 10 minutes or finish within 20 minutes of submission.
execution_failedThe task could not be completed.

Levels and policies

The policy only decides which levels count as NSFW. It never changes the probabilities or the level, so you can store the raw output and apply your own rules later.

Level"standard" (default)"strict"
L1 (lowest risk)passpass
L2passflagged
L3flaggedflagged
L4 (most explicit)flaggedflagged

Query a prediction task

GET https://api.nsfwcheckapi.com/v1/predictions/{id}

Use the task id and any API key of the same account. While status is "waiting" or "processing", output is null: keep polling every 1–2 seconds, and on 429 wait for the Retry-After seconds. When status is "succeeded", read output; when it is "failed", read error. See Get task details.

curl 'https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Code examples

Request

curl -X POST 'https://api.nsfwcheckapi.com/v1/predictions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: upload-8f2c1e7a9b3d4c5e' \
  -d '{
    "model": "general",
    "input": { "image": "https://images.example.com/photo.jpg" },
    "policy": { "sensitivity": "standard" }
  }'

Response

201 Created — the task was accepted:

{
  "id": "0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70",
  "model": "general",
  "status": "waiting",
  "policy": { "sensitivity": "standard" },
  "model_version": null,
  "output": null,
  "error": null,
  "created_at": "2026-10-22T08:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "urls": {
    "get": "https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70"
  }
}

200 OK from GET /v1/predictions/{id} once the task has succeeded:

{
  "id": "0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70",
  "model": "general",
  "status": "succeeded",
  "policy": { "sensitivity": "standard" },
  "model_version": "general-2026-08",
  "output": {
    "level": "L1",
    "probabilities": { "L1": 0.94, "L2": 0.04, "L3": 0.01, "L4": 0.01 },
    "is_nsfw": false
  },
  "error": null,
  "created_at": "2026-10-22T08:30:00.000Z",
  "started_at": "2026-10-22T08:30:00.412Z",
  "completed_at": "2026-10-22T08:30:01.268Z",
  "urls": {
    "get": "https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70"
  }
}