# List engines

> The engines and video models you can use, what each costs, and what each can do.

Source: https://developers.mnml.ai/docs/engines

`GET https://api.mnml.ai/v2/engines`

## Example request

**curl**

```bash
curl https://api.mnml.ai/v2/engines \
  -H "Authorization: Bearer $MNML_API_KEY"
```

**TypeScript**

```ts
const res = await fetch("https://api.mnml.ai/v2/engines", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MNML_API_KEY}`,
  },
});

const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://api.mnml.ai/v2/engines",
    headers={"Authorization": f"Bearer {os.environ['MNML_API_KEY']}"},
)

data = res.json()
```

## Example response (200)

```json
{
  "success": true,
  "data": {
    "engines": [
      {
        "id": "v4.6-ultra",
        "name": "v4.6",
        "tier": "primary",
        "default": true,
        "paid_only": false,
        "available": true,
        "prices": {
          "render_usd": 0.2475,
          "edit_usd": 0.099,
          "render": 25,
          "edit": 10
        },
        "capabilities": {
          "text_to_render": true,
          "masks": true,
          "edit_references": true,
          "max_references": 15
        }
      }
    ],
    "video_models": [
      {
        "id": "v2.0-flash",
        "name": "v2.0 · Flash",
        "default": true,
        "available": true,
        "prices": [
          {
            "duration_seconds": 10,
            "usd": 0.99,
            "credits": 100
          },
          {
            "duration_seconds": 15,
            "usd": 1.485,
            "credits": 150
          }
        ]
      }
    ]
  }
}
```

Read prices from this endpoint rather than hard-coding them. Studio and the API price every engine and edit from one list, so an option that costs more in Studio costs more here too. Prices are in [API credits](https://developers.mnml.ai/docs/account#amounts). The example shows one engine and one video model; the answer lists them all.

`available` is false for an engine or video model your account cannot use yet: some need an account that has topped up its API wallet.

## Headers

- `Authorization` (string, required): `Bearer mk_live_…`: your API key. See [Authentication](https://developers.mnml.ai/docs/authentication).

## Response

On success (`200`): Every engine, primary first. The JSON is `{ "success": true, "data": … }`, and inside `data`:

- `engines` (object[], required): Every render engine, current and legacy.
  - `id` (string, required): The id to send as `engine`.
  - `name` (string, required): Its mnml name, which `engine` also takes.
  - `tier` (string, required): `primary` for a current engine, `legacy` for an earlier one kept for older work. Values: `primary`, `legacy`.
  - `default` (boolean, required): True for the engine a render uses when it names none.
  - `paid_only` (boolean, required): True when the engine needs an account that has topped up its API wallet.
  - `available` (boolean, required): Whether this key’s account can use it now.
  - `prices` (object, required): What each call costs.
    - `render_usd` (number, required): One render, in US dollars.
    - `edit_usd` (number, required): One edit on this engine, in US dollars.
  - `capabilities` (object, required): What the engine can do.
    - `text_to_render` (boolean, required): Renders from a prompt alone, with no image.
    - `masks` (boolean, required): Takes an area for an edit: a `region` or a mask.
    - `edit_references` (boolean, required): Takes `references` on an edit as well as a render.
    - `max_references` (integer, required): The most `references` one call can send it.
- `video_models` (object[], required): Every video model.
  - `id` (string, required): The id to send as `model`.
  - `name` (string, required): Its mnml name, which `model` also takes.
  - `default` (boolean, required): True for the model a video uses when it names none.
  - `available` (boolean, required): Whether this key’s account can use it now. Video needs an account that has paid.
  - `prices` (object[], required): What a clip costs, by length.
    - `duration_seconds` (integer | null, required): The clip length to send as `duration_seconds`; `null` for a model with one fixed length.
    - `usd` (number, required): The price of one clip of that length, in US dollars.

**Response headers (4)**

- `X-Request-Id` (string): This request, for support and the console log.
- `RateLimit-Limit` (integer): Requests this key may make per minute.
- `RateLimit-Remaining` (integer): Requests left in the current minute.
- `RateLimit-Reset` (integer): Seconds until the current minute resets.

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | Every engine, primary first. |
| 401 | The API key is missing, malformed, unknown or revoked. |
| 429 | A limit was reached: requests per minute, or a daily or concurrency limit. |
| Other | Any other error, in the same envelope. |

Every error answers `{ "success": false, "error": { "code", "message" } }`. What each code means, and what to do, is on [Errors](https://developers.mnml.ai/docs/errors).