> ## 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.

# Image Generation Request

> Reference for the request body accepted by POST /image/generate.

Endpoint:

```text theme={"theme":"kanagawa-dragon"}
POST https://api.mynth.io/image/generate
```

## Request body

```json theme={"theme":"kanagawa-dragon"}
{
  "prompt": "Modern poster design for a jazz festival",
  "negative_prompt": "watermark, blurry text",
  "magic_prompt": true,
  "model": "google/gemini-3.1-flash-image",
  "size": {
    "type": "aspect_ratio",
    "aspectRatio": "4:5",
    "scale": "4k"
  },
  "count": 2,
  "inputs": [
    {
      "type": "image",
      "source": {
        "type": "url",
        "url": "https://example.com/reference.png"
      }
    }
  ],
  "output": {
    "format": "webp",
    "quality": 80
  },
  "webhook": {
    "dashboard": false,
    "custom": [
      {
        "url": "https://example.com/api/mynth-webhook?token=abc123"
      }
    ]
  },
  "rating": {
    "mode": "nsfw_sfw"
  },
  "metadata": {
    "requestId": "req_123"
  },
  "access": {
    "pat": {
      "enabled": true
    }
  }
}
```

## Fields

| Field             | Type               | Default                               | Notes                                                                                             |
| ----------------- | ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `prompt`          | `string`           | *required*                            | Positive prompt, 1–8192 characters.                                                               |
| `negative_prompt` | `string`           | —                                     | Optional negative prompt, 1–8192 characters.                                                      |
| `magic_prompt`    | `true`             | —                                     | Set to `true` to enable Mynth-side prompt enhancement.                                            |
| `model`           | `string`           | `"auto"`                              | A model ID or `"auto"`. Set a specific model in production.                                       |
| `size`            | `string` or object | `"auto"`                              | Presets, structured aspect ratios, or `"auto"`.                                                   |
| `count`           | `number`           | `1`                                   | Minimum `1`, maximum `20`.                                                                        |
| `inputs`          | `array`            | `[]`                                  | String URLs or structured image input objects. Maximum 20.                                        |
| `output`          | `object`           | `{ "format": "webp", "quality": 80 }` | `format` (`png`, `jpg`, `webp`) and `quality` (`1`–`100`).                                        |
| `webhook`         | `object`           | —                                     | `dashboard` (`false`) and `custom` (array of `{ url }`).                                          |
| `rating`          | `true` or object   | —                                     | `true`, `{ "mode": "nsfw_sfw" }`, or `{ "mode": "custom", "levels": [...] }`.                     |
| `destination`     | `string`           | —                                     | Name of a configured destination to deliver generated images to.                                  |
| `metadata`        | `object`           | —                                     | Arbitrary JSON, maximum 2 KB. Returned with the task and webhook payloads.                        |
| `access`          | `object`           | —                                     | `pat.enabled` (boolean, default `true`). Controls whether a task-scoped access token is returned. |

### Object details

**`inputs` entry:**

```json theme={"theme":"kanagawa-dragon"}
{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://example.com/reference.png"
  }
}
```

String URLs are a shorthand for image inputs. Structured entries use `type` and `source`.

**`webhook` object:**

```json theme={"theme":"kanagawa-dragon"}
{
  "dashboard": false,
  "custom": [{ "url": "https://example.com/hook" }]
}
```

Set `dashboard: false` to skip dashboard-managed webhooks for this task. Maximum 5 custom endpoints. Custom endpoints are not signed. See [Use Webhooks](/guides/use-webhooks).

**`access` object:**

```json theme={"theme":"kanagawa-dragon"}
{
  "pat": { "enabled": true }
}
```

Returns a `publicAccessToken` for browser-safe polling. See [Browser Polling](/tutorials/browser-polling).

## Prompt enhancement

Set `magic_prompt: true` to opt into Mynth-side prompt enhancement. When enabled, the enhanced prompt is returned in `result.magic_prompt` (with `positive` and optional `negative`).

## Size presets

* `square`
* `portrait`
* `landscape`
* `portrait_tall`
* `landscape_wide`
* `1:1`
* `2:3`
* `3:2`
* `3:4`
* `4:3`
* `4:5`
* `5:4`
* `9:16`
* `16:9`
* `21:9`
* `2:1`
* `1:2`
* `1:1_4k`
* `2:3_4k`
* `3:2_4k`
* `3:4_4k`
* `4:3_4k`
* `4:5_4k`
* `5:4_4k`
* `9:16_4k`
* `16:9_4k`
* `21:9_4k`
* `2:1_4k`
* `1:2_4k`

## Structured size objects

### Aspect ratio

```json theme={"theme":"kanagawa-dragon"}
{ "type": "aspect_ratio", "aspectRatio": "16:9" }
```

Supported aspect ratios:

* `1:1`
* `2:3`
* `3:2`
* `3:4`
* `4:3`
* `4:5`
* `5:4`
* `9:16`
* `16:9`
* `21:9`
* `2:1`
* `1:2`

Optional `scale` values:

* `base` (default)
* `4k`

When `scale: "4k"` is requested, models with dedicated 4K pricing are billed at their 4K rate.
For each successful output image, input images are billed as `perImage + perInput * inputs.length`.

### Auto

```json theme={"theme":"kanagawa-dragon"}
{ "type": "auto" }
```

Mynth picks the size automatically. When the model can size natively, that path
is used; otherwise Mynth resolves a size for you. This is not configurable.