# Generate image

> Queues an image generation and returns the task straight away — generation itself is asynchronous. Follow the task by polling its status or by receiving a webhook. The cost is reserved up front and reconciled when the task finishes, so a partial failure is refunded.

Creates an image task and returns its id. Nothing in the response is an image
yet. Wait for the task by [polling](https://mynth.io/docs/guides/poll-for-results.md) or with a
[webhook](https://mynth.io/docs/concepts/webhooks.md), or let the SDK's `image.generate()` wait
for you.

Always pass `model`. When it is omitted, the API uses `auto`, which is
experimental. See [the model field](https://mynth.io/docs/models.md#auto-is-experimental).
[Generate images](https://mynth.io/docs/guides/generate-images.md) covers sizes and the result.

`POST /image/generate`

**Auth:** API key or OAuth token

## Request body

- `prompt` (required, string) — Positive prompt. ≥ 1 characters, ≤ 8192 characters. Example `"Cute Cat"`.
- `model` (string) — Default `"auto"`. One of: `"alibaba/qwen-image-2.0"`, `"alibaba/qwen-image-2.0-pro"`, `"alibaba/qwen-image-3.0"`, `"alibaba/qwen-image-3.0-pro"`, `"auto"`, `"black-forest-labs/flux-1-schnell"`, `"black-forest-labs/flux.1-dev"`, `"black-forest-labs/flux.2-dev"`, `"black-forest-labs/flux.2-flex"`, `"black-forest-labs/flux.2-klein-4b"`, `"black-forest-labs/flux.2-max"`, `"black-forest-labs/flux.2-pro"`, `"bria/fibo-edit-1.5"`, `"bria/fibo-generate-1.5"`, `"bytedance/seedream-5.0-lite"`, `"bytedance/seedream-pro"`, `"circlestone-labs/anima"`, `"goofy-ai/prefect-pony-xl-lora"`, `"google/gemini-3-pro-image-preview"`, `"google/gemini-3.1-flash-image"`, `"google/gemini-3.1-flash-lite-image"`, `"imagineart/imagineart-1.5-pro"`, `"imagineart/imagineart-2.0"`, `"john6666/bismuth-illustrious-mix"`, `"klingai/kling-image-3.0"`, `"klingai/kling-image-o3"`, `"krea/krea-2-large"`, `"krea/krea-2-medium"`, `"krea/krea-2-turbo"`, `"luma/uni-1"`, `"luma/uni-1-max"`, `"maxfeifei8/one-obsession"`, `"meta/muse-image"`, `"microsoft/mai-image-2.6"`, `"microsoft/mai-image-2.6-flash"`, `"minimax/h3"`, `"openai/gpt-image-2"`, `"openai/gpt-image-2.5-flare"`, `"openai/gpt-image-2.5-sunburst"`, `"purplesmartai/pony-diffusion-v6-xl"`, `"recraft/recraft-v4"`, `"recraft/recraft-v4-pro"`, `"reve/reve"`, `"reve/reve-remix"`, `"sourceful/riverflow-2.0-pro"`, `"tongyi-mai/z-image"`, `"tongyi-mai/z-image-turbo"`, `"wan/wan2.6-image"`, `"wan/wan2.7-image"`, `"wan/wan2.7-image-pro"`, `"xai/grok-imagine-image"`, `"xai/grok-imagine-image-2.0"`, `"xai/grok-imagine-image-quality"`. Example `"black-forest-labs/flux.2-pro"`.
- `count` (number) — Default `1`. ≥ 1, ≤ 20.
- `access` (object) — Controls whether the create-task response should include a short-lived Public Access Token. That token can be passed to browser or client-side code for polling task status and task images without exposing your API key.
  - `pat` (required, object)
    - `enabled` (boolean) — Default `true`.
- `destination` (string) — ≥ 1 characters, ≤ 64 characters. Example `"bunny-prod"`.
- `inputs` ((string | object)[]) — ≤ 20 items.
  - **source + type**
    - `source` (required, object)
      - `type` (required, "url")
      - `url` (required, string)
    - `type` (required, "image")
    - `as` (string) — One of: `"auto"`, `"reference"`, `"source"`.
- `magic_prompt` (boolean)
- `metadata` (object)
- `negative_prompt` (string) — ≤ 8192 characters.
- `output` (object)
  - `format` (string) — One of: `"jpg"`, `"png"`, `"webp"`.
- `rating` (object | boolean) — One of: `true`.
  - **nsfw_sfw**
    - `mode` ("nsfw_sfw") — Default `"nsfw_sfw"`.
  - **custom**
    - `levels` (required, object[]) — ≥ 2 items, ≤ 7 items.
      - `description` (required, string) — ≥ 1 characters, ≤ 150 characters.
      - `value` (required, string) — ≥ 1 characters, ≤ 24 characters.
    - `mode` (required, "custom")
- `size` (object | string) — One of: `"16:9"`, `"16:9_4k"`, `"1:1"`, `"1:1_4k"`, `"1:2"`, `"1:2_4k"`, `"21:9"`, `"21:9_4k"`, `"2:1"`, `"2:1_4k"`, `"2:3"`, `"2:3_4k"`, `"3:2"`, `"3:2_4k"`, `"3:4"`, `"3:4_4k"`, `"4:3"`, `"4:3_4k"`, `"4:5"`, `"4:5_4k"`, `"5:4"`, `"5:4_4k"`, `"9:16"`, `"9:16_4k"`, `"auto"`, `"landscape"`, `"landscape_wide"`, `"portrait"`, `"portrait_tall"`, `"square"`.
  - **aspect_ratio**
    - `aspectRatio` (required, string) — One of: `"16:9"`, `"1:1"`, `"1:2"`, `"21:9"`, `"2:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"4:5"`, `"5:4"`, `"9:16"`.
    - `type` (required, "aspect_ratio")
    - `scale` (string) — Default `"base"`. One of: `"4k"`, `"base"`.
  - **auto**
    - `type` (required, "auto")
- `webhook` (object)
  - `custom` (object[]) — ≥ 1 items, ≤ 5 items.
    - `url` (required, string)
  - `dashboard` (boolean) — Set to false to disable dashboard-managed webhooks for this task. Request-level custom webhooks are still sent.

## Response

### 201 — Image generation task created

- `data` (required, object)
  - `estimatedCost` (required, string) — Estimated cost in USD reserved for this task. Failed images are refunded, so the final cost may be lower. Example `"0.03"`.
  - `taskId` (required, string) — Task ID Example `"tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP"`.
  - `access` (object) — Returned when `access.pat.enabled` is true.
    - `publicAccessToken` (required, string) — Short-lived Public Access Token for polling task status and image results. This token is safe to return to frontend code and can be used instead of your API key for polling public task state. Example `"pat_eyJhbGciOi..."`.

```json
{
  "data": {
    "estimatedCost": "0.03",
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "access": {
      "publicAccessToken": "pat_eyJhbGciOi..."
    }
  }
}
```

### 400 — Validation Error

- `success` (required, false)
- `error` (required, array)
- `data` (required, any)

```json
{
  "success": false,
  "error": []
}
```

## Request samples

### cURL

```bash
curl -X POST https://api.mynth.io/image/generate \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cute Cat",
    "model": "black-forest-labs/flux.2-pro",
    "destination": "bunny-prod"
  }'
```

### JavaScript

```ts
const response = await fetch("https://api.mynth.io/image/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MYNTH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "Cute Cat",
    "model": "black-forest-labs/flux.2-pro",
    "destination": "bunny-prod"
  }),
});

const { data } = await response.json();
```

The full schema for this endpoint is in the [OpenAPI document](https://api.mynth.io/openapi.json).