Image Rate Request - Mynth - Documentation

Endpoint:

POST https://api.mynth.io/image/rate

Authentication: API key or OAuth access token required. Public Access Tokens are not accepted. The endpoint is async only. It creates an image.rate task and returns 201 with a taskId. Poll task endpoints or use webhooks to get the rating result.

Request body

{
  "url": "https://example.com/photo-1.webp",
  "mode": "custom",
  "levels": [
    { "value": "safe", "description": "Safe for all audiences" },
    { "value": "sensitive", "description": "Contains mature or suggestive content" },
    { "value": "explicit", "description": "Explicit adult content" }
  ]
}

Minimal request (default nsfw_sfw scale):

{
  "url": "https://example.com/photo-1.webp"
}

Fields

Field	Type	Default	Notes
`url`	`string`	required	Image URL to rate. Must be an `http` or `https` URL.
`mode`	`string`	`nsfw_sfw`	`nsfw_sfw` for the built-in scale, or `custom`.
`levels`	`array`	—	Required when `mode` is `custom`. Defines the rating scale.

`levels` items

Each item in the levels array must have:

Field	Type	Constraints	Notes
`value`	`string`	1–24 characters	The string returned in the result for images at this level.
`description`	`string`	1–150 characters	Natural-language description used by the rating model.

Constraints for the levels array:

Minimum 2 items
Maximum 7 items

How the rating model uses levels The description of each level is passed directly to a vision language model (LLM), which selects the best match for the image. Because LLM inference is non-deterministic, results for borderline images may occasionally vary between requests. This endpoint is optimised for speed and accuracy at a high level of abstraction. Broad, clearly separated scales such as safe / suggestive / explicit or safe-for-children / safe-for-adults / nsfw perform reliably. Scales that depend on subtle visual distinctions — for example distinguishing between artistic and explicit nudity — are outside the intended scope and may produce inconsistent results. Test thoroughly before using such scales in production.

Response body

`201` — task created

{
  "data": {
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimatedCost": "0.0002"
  }
}

Field	Type	Notes
`data.taskId`	`string`	Task ID. Poll `/tasks/:id` or use webhooks for the result.
`data.estimatedCost`	`string`	Estimated cost in USD reserved for this task. Failed tasks are free.

When the task completes, GET /tasks/:id (or the webhook payload) includes:

{
  "result": {
    "url": "https://example.com/photo-1.webp",
    "level": "sfw"
  }
}

Field	Type	Notes
`url`	`string`	The submitted image URL.
`level`	`string`	The assigned rating value from the active scale.

When using the default scale, level is one of sfw or nsfw. When using custom levels, level is the value of the chosen level. If rating fails, the task status is failed with errors: [{ code, message? }]. Common codes: FETCH_FAILED, RATING_FAILED, UNKNOWN_ERROR. See Task error codes.

Limits

Constraint	Value
URLs per request	1
Custom levels	2–7
Level `value`	1–24 characters
Level `description`	1–150 characters

Pricing

Each request is priced at $0.0002. That amount is reserved from your account balance before processing begins. You are charged only when the task completes successfully — failed tasks release the reserve. If your balance is insufficient, the request returns 422 INSUFFICIENT_BALANCE.

Error responses

Status	Body	Cause
`400`	`{ success: false, errors: [...] }`	Request body fails schema validation.
`401`	`{ code: "UNAUTHORIZED", ... }`	Missing or invalid API key or OAuth access token.
`422`	`{ code: "INSUFFICIENT_BALANCE" }`	Account balance is too low to reserve the cost.

See Errors and Limits for the full error reference.

​Request body

​Fields

​levels items

​Response body

​201 — task created

​Limits

​Pricing

​Error responses