Image moderation

POST /v1/moderations/image classifies an image (URL or base64 data:) with one of three classifier models and returns an NSFW score from 0 to 1 plus a normal / flagged / nsfw label. The decision stays yours, nothing is blocked by this endpoint. GET /v1/moderation-models lists the classifiers and their prices.

POST/v1/moderations/imageBearer auth

Classify an image for NSFW content

Returns a confidence score (0.0–1.0) and label for the image at the given URL. You can select which classifier model to use via the optional model field, see GET /v1/moderation-models for available options with pricing.

When to call this:

Before sending an image to Real-ESRGAN or any other image-only model that doesn't have a prompt for upstream safety filters.
As part of your own user-generated-content moderation pipeline.
When you want a score you control, independent of our automatic pre-flight setting.

Billing: per-model pricing (see GET /v1/moderation-models). Settled immediately. Call costs appear in your dashboard alongside other predictions.

Model selection: pass the model field to choose a classifier. If omitted, your account's admin-assigned default is used (or the system default if none assigned).

Labels:

normal: score is below both thresholds.
flagged: score ≥ flagged threshold but < blocked threshold.
nsfw: score ≥ blocked threshold.

Notes:

Both http:// / https:// URLs and base64 data: URIs are supported.
Max image size is 25 MB.
The response model field tells you which classifier was used.

Request bodyrequired

Field	Type	Description
`image`required	string (uri)	Public HTTP(S) URL or base64 data URI of the image to classify. HTTP(S) URLs must be reachable either directly from our Iran-local servers (e.g., ArvanCloud) or via our outbound tunnel. Example: `https://s3.ir-thr-at1.arvanstorage.ir/bucket/photo.jpg`
`model`	string	Classifier model to use. Omit for your account's default. See GET /v1/moderation-models for available options with pricing. Example: `falcons-ai/nsfw_image_detection`

Example

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/moderations/image \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/photo.jpg",
    "model": "falcons-ai/nsfw_image_detection"
  }'

import requests

resp = requests.post(
    "https://api.hormouz.net/v1/moderations/image",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
    json={
        "image": "https://example.com/photo.jpg",
        "model": "falcons-ai/nsfw_image_detection",
    },
).json()
print(resp["label"], resp["score"])

const resp = await (await fetch("https://api.hormouz.net/v1/moderations/image", {
  method: "POST",
  headers: {
    Authorization: "Bearer ng-YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image: "https://example.com/photo.jpg",
    model: "falcons-ai/nsfw_image_detection",
  }),
})).json();
console.log(resp.label, resp.score);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"image": "https://example.com/photo.jpg",
		"model": "falcons-ai/nsfw_image_detection",
	})
	req, _ := http.NewRequest("POST", "https://api.hormouz.net/v1/moderations/image", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Label string  `json:"label"`
		Score float64 `json:"score"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Label, out.Score)
}

Responses

200

Classification completed.

400

Invalid image URL, unreachable source, or unsupported image format. The code distinguishes the cases:

INVALID_IMAGE_URL: URL malformed or empty.
IMAGE_FETCH_FAILED: could not download the bytes.
UNSUPPORTED_IMAGE_FORMAT: bytes can't be decoded; re-encode as JPEG, PNG, WebP, or GIF.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

402

Insufficient credit balance for the check.

409

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

413

Image exceeds the maximum allowed size (25 MB default).

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

499

Your HTTP client cancelled the request before the gateway finished. No charge: the hold has been released. The most common cause is a 30 s default client timeout against a model whose p95 latency is 45-60 s; bump your client timeout to 120 s.

Retries with the same Idempotency-Key will replay this 499 forever (the prior outcome is "you cancelled"). For an actual re-attempt, mint a fresh Idempotency-Key. See docs/CUSTOMER_ERROR_HANDLING.md §3 for the full contract.

{
  "error": {
    "code": "CLIENT_CLOSED",
    "message": "Client disconnected before response",
    "status": 499
  }
}

503

Classifier or upload upstream temporarily unavailable.

504

The gateway's 120 s upstream deadline elapsed before the upstream provider produced a response. Retry with the same Idempotency-Key so a delayed-but-eventually-successful upstream call can be replayed instead of re-charged. Consider switching to a faster model or capping max_tokens if this recurs.

{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Upstream did not respond before timeout",
    "status": 504
  }
}

GET/v1/moderation-modelsBearer auth

List available content moderation models

Returns the available NSFW classifier models with display names, per-check pricing, and estimated speed. Use the id from this list in the model field of POST /v1/moderations/image.