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.

/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	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, /models.txt	agents: id, name, type, capabilities, price
`npx @mynthio/cli models list`	the terminal, with filters

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

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:

{
  "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 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 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: what to check before you pin one.
Video models: the video models and their limits.
Pricing: how the catalog price becomes a charge.

Find a model#

Reading a catalog entry#

auto is experimental#

Fields a model cannot serve#

Next steps#

`auto` is experimental#