> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# Models

> Use auto and inspect the model catalog

Use `model: "auto"` to let JoyToken select the concrete model during routing, or send a `modelName` from the catalog to pin a specific model.

> **Note**
>
> A `modelName` from the catalog can be sent as the request `model` to pin that model. See [Routing](/user-guide/routing#pin-a-specific-model) for how a pinned model behaves.

## Recommended Choice

| Scenario         | Request                                 |
| ---------------- | --------------------------------------- |
| New integration  | `model: "auto"`                         |
| Cost-first       | `model: "auto"` + `tier: "economy"`     |
| Balanced default | `model: "auto"` + `tier: "standard"`    |
| Quality-first    | `model: "auto"` + `tier: "premium"`     |
| Pin one model    | `model: "<modelName from the catalog>"` |

## Auto Routing

```json
{
  "model": "auto",
  "tier": "standard",
  "messages": [
    { "role": "user", "content": "Write a short onboarding message." }
  ]
}
```

`auto` lets JoyToken choose a model within API key policy, tier, wallet balance, and model-pool availability.

## List Models

Set `JOY_TOKEN_API_BASE_URL` from [Environments](/user-guide/environments) before calling the model catalog.

```bash
curl "$JOY_TOKEN_API_BASE_URL/api/v1/models?locale=en"
```

Set `locale=en` for English descriptions or `locale=zh` for Chinese descriptions. If `locale` is omitted, the API defaults to English.

Common filter:

```bash
curl "$JOY_TOKEN_API_BASE_URL/api/v1/models?locale=en&tier=standard&feature_tag=code"
```

`GET /api/v1/models` is public. The metadata and pricing endpoints require an API key. Send either `Authorization: Bearer $JOY_TOKEN_API_KEY` or `X-API-Key: $JOY_TOKEN_API_KEY`.

## Catalog Metadata

Use catalog metadata to build filters without hard-coding provider names or capability tags.

```bash
curl "$JOY_TOKEN_API_BASE_URL/api/v1/models/meta" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY"
```

The response contains `tiers`, `skus`, `featureTags`, `industryPacks`, `providers`, and `updatedAt`.

## Pricing

```bash
curl "$JOY_TOKEN_API_BASE_URL/api/v1/pricing" \
  -H "X-API-Key: $JOY_TOKEN_API_KEY"
```

The response lists customer-facing tier exchange-rate descriptions. This endpoint requires an API key.

## Model Fields

| Field                          | Meaning                                                              |
| ------------------------------ | -------------------------------------------------------------------- |
| `modelName`                    | Catalog model name; send it as the request `model` to pin this model |
| `displayName` / `alias`        | Always `auto` in the current response                                |
| `tier`                         | Billing and routing tier                                             |
| `tags`                         | Product tags                                                         |
| `description`                  | Localized description selected by `locale`                           |
| `provider`                     | Always `auto` in the current response                                |
| `featureTags`                  | Capability tags                                                      |
| `scenarioTags`                 | Scenario tags                                                        |
| `mciScore`                     | Catalog score                                                        |
| `customerInputMtok`            | Input price in Cr / MTok                                             |
| `customerOutputMtok`           | Output price in Cr / MTok                                            |
| `customerCachereadMtok`        | Cache-read price in Cr / MTok                                        |
| `customerCachewriteMtok`       | Cache-write price in Cr / MTok                                       |
| `customerImageInputMtok`       | Image-input price as a decimal string; empty when unavailable        |
| `customerImageCachedInputMtok` | Cached image-input price as a decimal string; empty when unavailable |
| `customerImageOutputMtok`      | Image-output price as a decimal string; empty when unavailable       |

## Model Is Listed But Request Fails

The model catalog shows the models available to JoyToken routing. Send `model: "auto"` to let JoyToken choose, or send a catalog `modelName` to pin one. Check:

| Check             | Description                      |
| ----------------- | -------------------------------- |
| API key policy    | tier and model restrictions      |
| Source IP         | whether the key policy allows it |
| Wallet and budget | main wallet has balance          |