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 answers 400 validation_error. When the id is
close to a real one, such as flux.2-pro for black-forest-labs/flux.2-pro,
the message suggests it. See
validation errors.
/image/rate, /image/alt, /image/review, /image/remove-background, and
/image/upscale take no model. Mynth picks the model behind them and replaces it when a
better one is available, without changing the endpoint.
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.05Read the catalog at runtime rather than hardcoding a model list or prices. Models are added, and prices change when providers change theirs.
GET /models returns every enabled model in data, sorted by id:
{
"id": "black-forest-labs/flux.2-pro",
"display_name": "FLUX.2 Pro",
"type": "image",
"modes": {
"txt->img": {},
"img->img": { "inputs": { "rules": [{ "type": "image", "max": 3 }] } }
},
"pricing": { "per_image": { "base": "0.03" }, "per_input": "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. max_total 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 experimentalPass 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:
inputs or size.estimate_kind: "upper_bound".result.model and releases the rest of the hold._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.
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 pinned model without 4k | 400 validation_error at create, nothing queued |
A _4k size with auto, landing on a model without 4k | Accepted, then 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 |
A video tier, duration, or audio the model rejects | 400 validation_error at create |
| A field that is not in the schema | 400 validation_error at create, naming the field |
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.