> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mynth.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Image Content

> Use POST /image/rate to classify the content of one or more images by URL.

The `/image/rate` endpoint accepts up to 10 image URLs and returns a content rating for each one. By default the response is synchronous — results are returned in the same HTTP response, not via polling. Set `"sync": false` to queue the task asynchronously and receive a `202` with a task ID instead.

## Pricing

`/image/rate` is priced at **\$0.0002 per image**. Only successfully rated images are charged.

The full amount for all submitted URLs is reserved up front. If a URL fails, the unused reserve for that image is released.

## Rate images with the default scale

The default scale has two levels: `sfw` and `nsfw`.

```bash theme={"theme":"kanagawa-dragon"}
curl https://api.mynth.io/image/rate \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "nsfw_sfw",
    "urls": [
      "https://example.com/photo-1.webp",
      "https://example.com/photo-2.webp"
    ]
  }'
```

Response:

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "completed",
      "cost": "0.00040000"
    },
    "results": [
      { "status": "success", "url": "https://example.com/photo-1.webp", "level": "sfw" },
      { "status": "success", "url": "https://example.com/photo-2.webp", "level": "nsfw" }
    ]
  }
}
```

## Rate images with custom levels

Replace the default scale with 2 to 7 custom levels. Each level requires a `value` (the string returned in the result) and a `description` (used by the rating model to decide which level applies).

<Note>
  **Ratings are performed by a vision language model and are non-deterministic.** Results for
  borderline images may vary between requests. The endpoint is optimised for speed and accuracy
  at a high level of abstraction — it is not a fine-grained tagging or classification pipeline.

  Broad, clearly separated scales work best: `safe` / `suggestive` / `explicit`, or
  `safe-for-children` / `safe-for-adults` / `nsfw` are reliable choices. Scales that rely on
  subtle visual distinctions — such as `subtle-nudity` vs `artistic-nudity` vs
  `explicit-nudity` — are outside the intended use-case and may produce inconsistent results.
  If you need that level of granularity, test thoroughly before relying on the output in
  production.
</Note>

```bash theme={"theme":"kanagawa-dragon"}
curl https://api.mynth.io/image/rate \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "custom",
    "urls": ["https://example.com/photo-1.webp"],
    "levels": [
      { "value": "g",    "description": "Suitable for all audiences" },
      { "value": "pg",   "description": "Mild content, suitable for general audiences" },
      { "value": "pg13", "description": "May contain mature themes, not suitable for children" },
      { "value": "r",    "description": "Restricted content, adult themes or partial nudity" },
      { "value": "x",    "description": "Explicit adult content" }
    ]
  }'
```

Response:

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "completed",
      "cost": "0.00020000"
    },
    "results": [{ "status": "success", "url": "https://example.com/photo-1.webp", "level": "pg" }]
  }
}
```

## Handle per-image errors

Ratings are processed in parallel. If a single image cannot be rated, its result has `status: "failed"` and an `error` object. Other images in the same request are not affected.

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "completed",
      "cost": "0.00020000"
    },
    "results": [
      { "status": "success", "url": "https://example.com/photo-1.webp", "level": "sfw" },
      {
        "status": "failed",
        "url": "https://example.com/photo-2.webp",
        "error": { "code": "RATING_FAILED" }
      }
    ]
  }
}
```

Only successfully rated images are charged, so the `cost` above reflects one successful rating. The full amount for all submitted URLs is reserved up front and the unused reserve is released for any images that fail.

Check each item before reading the `level` field:

```ts theme={"theme":"kanagawa-dragon"}
for (const item of response.data.results) {
  if (item.status === "failed") {
    console.error("Failed to rate image:", item.url, item.error.code);
  } else {
    console.log(item.url, "→", item.level);
  }
}
```

## Rate images generated by Mynth

If you want to rate images that Mynth generated, use the `rating` option on the generation request instead. This runs the rating during generation and attaches the result to each image.

See [Use Content Rating](/guides/use-content-rating) for details.