# Generate images

> The image generation request, every field it takes, the sizes you can ask for, and what comes back.

`POST /image/generate` creates an image task. Send a `model` id and a
`prompt`. Everything else is optional.

**SDK**

```ts
import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

const task = await mynth.image.generate({
  model: "black-forest-labs/flux.2-pro",
  prompt: "A lighthouse at dusk, film grain",
  size: "landscape",
});

console.log(task.urls[0]);
```

**CLI**

```bash
npx @mynthio/cli image generate \
  -m black-forest-labs/flux.2-pro \
  -p "A lighthouse at dusk, film grain" \
  -s landscape
```

**REST**

```bash
curl https://api.mynth.io/image/generate \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"black-forest-labs/flux.2-pro","prompt":"A lighthouse at dusk, film grain","size":"landscape"}'
```

The SDK and the CLI wait and return the finished task. The REST call returns
at once with a task id:

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

Collect the result by [polling](https://mynth.io/docs/guides/poll-for-results.md) or with a
[webhook](https://mynth.io/docs/concepts/webhooks.md).

## Fields

Every image model takes this body.

| Field             | Default         | Notes                                                                                      |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------ |
| `model`           | `auto`          | A catalog id. Always pass one. [`auto` is experimental](https://mynth.io/docs/models.md#auto-is-experimental) |
| `prompt`          | required        | 1 to 8192 characters                                                                       |
| `negative_prompt` | none            | Up to 8192 characters. Dropped without an error if the model has none                      |
| `count`           | `1`             | 1 to 20. Each image succeeds or fails on its own                                           |
| `size`            | `auto`          | See [sizes](#sizes)                                                                        |
| `inputs`          | none            | Up to 20 input images. See [image to image](https://mynth.io/docs/guides/image-to-image.md)                   |
| `magic_prompt`    | `false`         | Rewrite the prompt first. See [enhance prompts](https://mynth.io/docs/guides/enhance-prompts.md)              |
| `rating`          | none            | `true`, or a rating object. See [rate images](https://mynth.io/docs/guides/rate-images.md#on-a-generation)    |
| `output.format`   | the provider's  | `png`, `jpg`, or `webp`                                                                    |
| `destination`     | none            | A destination name. See [destinations](https://mynth.io/docs/concepts/destinations.md)                        |
| `webhook`         | registered ones | Per-request URLs. See [webhooks](https://mynth.io/docs/concepts/webhooks.md#per-request-webhooks)             |
| `metadata`        | none            | A JSON object up to 2048 bytes, returned on the task and in webhooks                       |
| `access`          | token issued    | `{ "pat": { "enabled": false } }` skips the browser token                                  |

Fields the schema does not know are dropped without an error. If a setting
seems to have no effect, check the task's `request`, which shows the body as
it was accepted.

## Sizes

You ask for a shape, not pixels, and Mynth picks the closest size the model
serves. Omit `size`, or send `"auto"`, and Mynth picks a ratio that suits the
prompt.

| `size`                                                                                | Result                    |
| ------------------------------------------------------------------------------------- | ------------------------- |
| `square`, `portrait`, `landscape`, `portrait_tall`, `landscape_wide`                  | 1:1, 2:3, 3:2, 9:16, 16:9 |
| `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `2:1`, `1:2` | that ratio                |
| Any ratio with `_4k`, such as `16:9_4k`                                               | that ratio at 4k          |
| `{ "type": "aspect_ratio", "aspectRatio": "16:9", "scale": "4k" }`                    | the same, as an object    |

A ratio the model has no preset for snaps to the closest one it serves. A 4k
size costs `perImage["4k"]` and needs a model that has it. On a model without
4k the task fails with `CAPABILITY_NOT_SUPPORTED`.

## What comes back

A completed task has one entry in `result.images` per requested image:

```json
{
  "model": "black-forest-labs/flux.2-pro",
  "images": [
    {
      "status": "success",
      "id": "img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk",
      "url": "https://cdn.mynth.io/images/img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk.webp",
      "mynth_url": "https://cdn.mynth.io/images/img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk.webp",
      "size": "1536x1024",
      "format": "webp"
    }
  ]
}
```

- Check `status` on every image. One image failing does not fail the task.
  See [tasks](https://mynth.io/docs/concepts/tasks.md#completed-does-not-mean-every-item-worked).
- `url` is where the file ended up: your storage when you named a
  destination, otherwise the same as `mynth_url`.
- `size` is the delivered file in `{width}x{height}` pixels.
- `result.model` is the model that ran.
- The file is served for 7 days. See [file lifetimes](https://mynth.io/docs/concepts/tasks.md#file-lifetimes).

Every field of the result is on [the task object](https://mynth.io/docs/api-reference/task-object.md#imagegenerate).

## Price

The create response holds `estimatedCost`, and you pay only for the images
that succeed. [Pricing](https://mynth.io/docs/pricing.md#image-price) has the formula, and
[estimate cost](https://mynth.io/docs/guides/estimate-cost.md) prices a body without generating.

## Next steps

- [Choosing an image model](https://mynth.io/docs/models/choosing.md): what to check before you pin an id.
- [Image to image](https://mynth.io/docs/guides/image-to-image.md): send input images.
- [Poll for results](https://mynth.io/docs/guides/poll-for-results.md): collect the task over REST.