# 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": {
    "task_id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimated_cost": "0.03"
  }
}
```

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`             | A whole number, 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                                                        |
| `generate_public_access_token` | `false`         | `true` returns a browser token as `public_access_token`. See [from a browser](https://mynth.io/docs/guides/poll-for-results.md#from-a-browser) |

A field the schema does not define answers `400 validation_error`, naming
it, so a typo never runs as an ignored setting. The task's `request` shows the
body as it was accepted, with defaults filled in.

## 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", "aspect_ratio": "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 `per_image["4k"]` and needs a model that has it. On a model without
4k the create answers `400 validation_error` with the size to use instead, and
nothing is queued. With `model: "auto"` the model is picked later, so the task
fails with `capability_not_supported` instead.

## 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 `estimated_cost`, 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.