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

# 模型

> 使用 auto 并查看模型目录

使用 `model: "auto"` 时由 JoyToken 在路由过程中选择具体模型；也可以传入模型目录中的 `modelName`，把请求固定到指定模型。

> **Note**
>
> 模型目录中的 `modelName` 可以作为请求的 `model` 传入，用于指定模型。指定模型的行为请参考 [路由](/zh/user-guide/routing#指定模型)。

## 推荐选择

| 场景   | 写法                                   |
| ---- | ------------------------------------ |
| 新接入  | `model: "auto"`                      |
| 成本优先 | `model: "auto"` + `tier: "economy"`  |
| 默认平衡 | `model: "auto"` + `tier: "standard"` |
| 质量优先 | `model: "auto"` + `tier: "premium"`  |
| 指定模型 | `model: "<模型目录中的 modelName>"`        |

## 自动路由

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

`auto` 会在 API Key 策略、tier、钱包余额和模型池状态允许的范围内选择模型。

## 获取模型目录

调用模型目录前，先从 [环境](/zh/user-guide/environments) 选择并设置 `JOY_TOKEN_API_BASE_URL`。

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

`locale=zh` 返回中文描述，`locale=en` 返回英文描述；不传 `locale` 时默认返回英文。

常用筛选：

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

`GET /api/v1/models` 是公开接口。元数据和价格接口需要 API Key，可发送 `Authorization: Bearer $JOY_TOKEN_API_KEY` 或 `X-API-Key: $JOY_TOKEN_API_KEY`。

## 目录筛选元数据

用目录元数据构建筛选器，不需要在应用里写死提供商名称或能力标签。

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

响应包含 `tiers`、`skus`、`featureTags`、`industryPacks`、`providers` 和 `updatedAt`。

## 价格详情

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

响应列出面向客户的档位兑换价格的说明。此接口必须提供 API Key。

## 模型字段

| 字段                             | 含义                                |
| ------------------------------ | --------------------------------- |
| `modelName`                    | 目录中的模型名；作为请求的 `model` 传入即可指定该模型   |
| `displayName` / `alias`        | 当前响应始终为 `auto`                    |
| `tier`                         | 计费和路由档位                           |
| `tags`                         | 商品标签                              |
| `description`                  | 由 `locale` 选择语言的模型说明              |
| `provider`                     | 当前响应始终为 `auto`                    |
| `featureTags`                  | 能力标签                              |
| `scenarioTags`                 | 场景标签                              |
| `mciScore`                     | 目录评分                              |
| `customerInputMtok`            | 输入价格，单位 Cr / MTok                 |
| `customerOutputMtok`           | 输出价格，单位 Cr / MTok                 |
| `customerCachereadMtok`        | 缓存读取价格，单位 Cr / MTok               |
| `customerCachewriteMtok`       | 缓存写入价格，单位 Cr / MTok               |
| `customerImageInputMtok`       | 图片输入价格，decimal string；不可用时为空字符串   |
| `customerImageCachedInputMtok` | 图片缓存输入价格，decimal string；不可用时为空字符串 |
| `customerImageOutputMtok`      | 图片输出价格，decimal string；不可用时为空字符串   |

## 模型列表能看到但请求失败

模型目录展示 JoyToken 路由可使用的模型。发送 `model: "auto"` 由 JoyToken 选择，或传入目录中的 `modelName` 指定模型。失败时检查：

| 检查项        | 说明           |
| ---------- | ------------ |
| API Key 策略 | tier 和模型限制   |
| 请求来源 IP    | 是否被 Key 策略允许 |
| 钱包和预算      | 主钱包是否有余额     |