# The model field

> What the model field accepts, where to read a model's modes, input rules and price, why to pass an explicit id instead of auto, and what happens when a model cannot serve a field.

`model` decides which generation model runs. Every model takes the same
request body, so switching models is a change to this one field.

Model ids are `vendor/name`, spelled exactly as the catalog prints them, for
example `black-forest-labs/flux.2-pro` or `bytedance/seedance-2.0-mini`. There
are no aliases.

| Endpoint               | `model` accepts              | When omitted          |
| ---------------------- | ---------------------------- | --------------------- |
| `POST /image/generate` | an image model id, or `auto` | `auto` (experimental) |
| `POST /video/generate` | a video model id             | required              |

An id that is not in the catalog fails schema validation with a `400`. See
[errors](https://mynth.io/docs/api-reference/errors.md#schema-rejections-use-a-different-shape).

`/image/rate`, `/image/alt`, `/image/review`, and `/image/remove-background`
take no `model`. Mynth picks the model behind them and replaces it when a
better one is available, without changing the endpoint.

## Find a model

The catalog is public, and none of these need an API key:

| Surface                                                  | Good for                                              |
| -------------------------------------------------------- | ----------------------------------------------------- |
| [mynth.io/models](https://mynth.io/models)                               | browsing and filtering, one page per model            |
| `GET https://api.mynth.io/models`                        | modes, input rules and pricing, as the SDK types them |
| [/models.json](https://mynth.io/models.json), [/models.txt](https://mynth.io/models.txt) | agents: id, name, type, capabilities, price           |
| `npx @mynthio/cli models list`                           | the terminal, with filters                            |

**CLI**

```bash
npx @mynthio/cli models list --type image --capability img2img --max-price 0.05
```

**SDK**

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

const models = await new Mynth().models.list(); // no key needed
const imageModels = models.filter((model) => model.type === "image");
```

Read the catalog at runtime rather than hardcoding a model list or prices.
Models are added, and prices change when providers change theirs.

## Reading a catalog entry

`GET /models` returns every enabled model in `data`, sorted by id:

```json
{
  "id": "black-forest-labs/flux.2-pro",
  "displayName": "FLUX.2 Pro",
  "type": "image",
  "modes": {
    "txt->img": {},
    "img->img": { "inputs": { "rules": [{ "type": "image", "max": 3 }] } }
  },
  "pricing": { "perImage": { "base": "0.03" }, "perInput": "0.03" }
}
```

**`modes`** is what the model serves on Mynth today, which can be less than
the vendor advertises. Images use `txt->img` and `img->img`. Video uses
`txt->vid` and `img->vid`. A missing mode cannot be used, and a mode without
`inputs` takes no images.

**`inputs.rules`** is the contract for the request's `inputs` array. Each rule
covers one kind of input with a `max`, plus a `min` when that kind is
required. A rule's `kind` is the value you put in `inputs[].as`: `source` or
`reference` for images, `first_frame` or `last_frame` for video. A rule
without a `kind` accepts any image. `maxTotal` caps the whole array.

**`pricing`** is decimal strings in USD, or `null` when the model has no price
on file. [Pricing](https://mynth.io/docs/pricing.md#where-prices-come-from) explains each field.

The catalog does not publish pixel sizes. You ask for an aspect ratio and a
scale, and Mynth maps it to the nearest size the model serves.
[/models.json](https://mynth.io/models.json) adds a `supports` list per model, where `4k`
means the model has both 4k sizes and a 4k price.

## `auto` is experimental

Pass a catalog id on every image request. When `model` is omitted, the API
uses `auto`, which is experimental. It has not picked models well, it is not
maintained as a model picker, and it is not something to build a product on.
The API will keep accepting it.

When a request does send `auto`:

- It chooses a model by reading the prompt and nothing else. It does not
  look at `inputs` or `size`.
- Creating the task holds a flat $0.20 per image. The estimate endpoint
  returns that hold with `estimateKind: "upper_bound"`.
- On completion Mynth charges the published price of the model in
  `result.model` and releases the rest of the hold.
- An edit or a `_4k` size can land on a model that cannot serve it. The task
  then fails with `CAPABILITY_NOT_SUPPORTED`, the hold is released, and
  nothing is charged.

With an explicit id, the price is exact before you send, and input and size
problems are rejected at create instead of failing later.

## Fields a model cannot serve

There is no per-model options bag, and no request field for steps, guidance,
or a scheduler. What differs between models is how each reacts to a field it
cannot serve:

| You send                                                   | Result                                                        |
| ---------------------------------------------------------- | ------------------------------------------------------------- |
| A `size` ratio the model has no preset for                 | Snaps to the closest ratio it serves                          |
| A `_4k` size on a model without 4k                         | The task fails with `CAPABILITY_NOT_SUPPORTED`                |
| `inputs` a pinned model cannot take                        | `400 VALIDATION_ERROR` at create, nothing queued              |
| `inputs` with `auto`, landing on a model that cannot edit  | Accepted, then the task fails with `CAPABILITY_NOT_SUPPORTED` |
| `negative_prompt` to a model without one                   | Dropped before the provider call, no error                    |
| `resolution`, `duration`, or `audio` a video model rejects | `400 VALIDATION_ERROR` at create                              |
| A field that is not in the schema                          | Dropped, no error                                             |

The two `CAPABILITY_NOT_SUPPORTED` rows fail the whole task rather than one
image, because the model, inputs, and size are resolved once before any image
is generated.

## Next steps

- [Choosing an image model](https://mynth.io/docs/models/choosing.md): what to check before you pin one.
- [Video models](https://mynth.io/docs/models/video.md): the video models and their limits.
- [Pricing](https://mynth.io/docs/pricing.md): how the catalog price becomes a charge.