# Introduction

> Mynth is one HTTP API in front of many image and video models. Send a model id and a prompt, get back a task, collect the file.

Mynth is one API in front of many image and video models. You send a model id
and a prompt. Mynth routes the request to a provider, retries on another one
when it fails, sizes the output for that model, and hands you back a file URL.
Switching models is a change to one field.

Every model takes the same request body. There is no per-provider SDK, no
per-model options bag, and no field that only one provider understands.

## How a generation runs

```text
POST /image/generate  or  POST /video/generate
  │
  ▼
201 { taskId, estimatedCost }      the estimate is held on your balance
  │
  ├─ wait in the SDK, poll the task, or receive a webhook
  ▼
task completed
  result.images[].url              a file URL, kept for 7 days
                                   or your own bucket, if you named a destination
```

There is no synchronous generate endpoint. `mynth.image.generate()` in the SDK
looks synchronous because it creates the task and polls it for you.
[Tasks](https://mynth.io/docs/concepts/tasks.md) covers statuses, partial failure, and how long
files are kept.

## Rules worth knowing first

- **Pass a model id.** Ids are `vendor/name`, copied from the
  [catalog](https://mynth.io/models), for example `black-forest-labs/flux.2-pro`. There are no
  aliases. Image generation accepts `auto` and uses it when `model` is
  omitted, but `auto` is experimental. See [the model field](https://mynth.io/docs/models.md#auto-is-experimental).
- **Keep the API key on the server.** A browser polls one task with the
  short-lived `pat_` token the create call returns. See
  [authentication](https://mynth.io/docs/authentication.md).
- **`completed` does not mean every image worked.** Each item in
  `result.images` or `result.videos` has its own `status`.
- **Mynth is not a file host.** Generated files are served for 7 days. Name a
  [destination](https://mynth.io/docs/concepts/destinations.md) or copy the file when the task
  completes.
- **Read prices, don't copy them.** Prices live in the catalog and in the
  estimate endpoints. See [pricing](https://mynth.io/docs/pricing.md).
- **Mynth does not moderate prompts.** A refusal comes from the provider. See
  [prompts and images](https://mynth.io/docs/concepts/prompts.md).

## Where to start

- [Getting started](https://mynth.io/docs/getting-started.md): a key and a first image, with the SDK, REST or the CLI.
- [Authentication](https://mynth.io/docs/authentication.md): `mak_` keys, scopes, spending limits, and the `pat_` token.
- [Tasks](https://mynth.io/docs/concepts/tasks.md): statuses, partial failure, and the ways to collect a result.
- [API reference](https://mynth.io/docs/api-reference.md): every endpoint, generated from the OpenAPI document.

## For agents

Every docs page is also plain markdown. Append `.md` to its URL, or send
`Accept: text/markdown`. This page is [/docs.md](https://mynth.io/docs.md), the index is
[/llms.txt](https://mynth.io/llms.txt), and every page in one file is
[/llms-full.txt](https://mynth.io/llms-full.txt). None of it needs an account.

```bash
npx @mynthio/cli docs list
npx @mynthio/cli docs get getting-started
```

The model catalog is public too: [/models.json](https://mynth.io/models.json) and
`GET https://api.mynth.io/models`. [llms.txt](https://mynth.io/docs/sdks/agents/llms-txt.md) has
the details.