> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型价格接口

>  - GET /api/pricing/model 读取模型展示价
- 只读 data.pricing；effective_rates 为实付
- 工具价需自行 × price_factor
- 契约通用：TokenPricingV2 模型均适用 

以 `qwen3.8-max` 为例说明；`data.pricing` 的结构对所有走 **TokenPricingV2** 的模型通用。

```http theme={null}
GET /api/pricing/model?model=qwen3.8-max
```

完整模型能力与计费口径见 [qwen3.8-max 接入指南](/cn/api-reference/texts/qwen3.8-max/guide)。

<Note>
  本接口**无需鉴权**，不必传 `Authorization`。
</Note>

## 请求参数

<ParamField query="model" type="string" required>
  模型 ID，例如 `qwen3.8-max`。必填；不传会返回 `400 Missing model parameter`。
</ParamField>

## 只读 `data.pricing`

响应里可能有多个价格相关块，**前端只应读 `data.pricing`**：

| 块                    | 用途          | 前端          |
| -------------------- | ----------- | ----------- |
| `data.pricing`       | 扁平、自描述的展示视图 | ✅ **只读这个**  |
| `data.token_price`   | 历史扁平副本      | ❌ 兼容保留，会漏字段 |
| `data.token_pricing` | 内部快照        | ❌ 含实现细节     |

`token_price` **可能缺少** `explicit_cached_input` 等字段，按它估价会偏高。新计费维度只会进入 `pricing`。

示例对比：

```json theme={null}
{
  "token_price": {
    "input": 1.714286,
    "cached_input": 0.214286,
    "cache_write": 2.142857,
    "output": 5.142857
  },
  "pricing": {
    "rates": {
      "input": 1.714286,
      "cached_input": 0.214286,
      "cache_write": 2.142857,
      "explicit_cached_input": 0.142857,
      "output": 5.142857
    }
  }
}
```

## `rates` 与 `effective_rates`

| 字段                | 含义                                 |
| ----------------- | ---------------------------------- |
| `rates`           | 划线价 / 原价                           |
| `effective_rates` | **实付价**（已乘折扣）                      |
| `discount_rate`   | 模型折扣（无折扣为 `1`）                     |
| `group_ratio`     | 分组倍率                               |
| `price_factor`    | `discount_rate × group_ratio`，唯一乘数 |

```json theme={null}
{
  "discount_rate": 1,
  "group_ratio": 0.8,
  "price_factor": 0.8,
  "rates": { "input": 1.714286, "output": 5.142857 },
  "effective_rates": { "input": 1.3714288, "output": 4.1142856 }
}
```

**展示价直接用 `effective_rates`，不要自己再乘。** 需要同时显示划线价时再用 `rates`。

<Note>
  `group` 常为 `default`：价格页面向访客统一按 default 报价。用户真实扣费按其所属分组，**可能低于展示价**。
</Note>

`rates` / `effective_rates` 的 `unit` 一般为 **`usd_per_million_tokens`**（每百万 token 美元价）。

## 工具价：`extras.tools` 只有原价

这是当前接口的不对称点：

|          | 原价                      | 实付                                       |
| -------- | ----------------------- | ---------------------------------------- |
| token    | `rates`                 | `effective_rates`（后端已算好）                 |
| **内置工具** | `extras.tools[x].price` | **无 effective 字段，前端自己 × `price_factor`** |

```js theme={null}
const listed = pricing.extras.tools.web_search.price; // 原价
const actual = listed * pricing.price_factor; // 展示 / 估算用这个
```

按 `unit` 换算，**不要写死「每千次」**：

| `unit`                 | 含义         | 费用                        |
| ---------------------- | ---------- | ------------------------- |
| `usd_per_1000_queries` | 每 1000 次调用 | `price / 1000 × 次数`       |
| `usd_per_page`         | 每页         | `price × 页数`（**不除 1000**） |

## 字段缺省的三态语义

| 情况        | JSON                                | 含义                    |
| --------- | ----------------------------------- | --------------------- |
| 有值        | `"explicit_cached_input": 0.142857` | 按该价收费                 |
| **整键不出现** | —                                   | **该维度不适用**（不是 0、不是免费） |
| 显式 `0`    | `"price": 0`                        | **确实免费**，应显示「免费」      |

示例：

* **`output_thinking` 不出现** → 只有一个输出价，**不要**渲染成「思考免费」。`qwen3.8-max` 思考不可关，官方只公布一个输出价。
* **`extras.google_web_search` 不出现** → Vertex 专有字段；百炼类搜索在 `extras.tools.web_search`。
* `extras.tools` 里某工具 `price: 0` → **显式免费**（如限时免费），如实展示。

## 是否多档：只看 `tier_count`

```json theme={null}
{
  "billing_type": "tiered_token",
  "tier_count": 1
}
```

| 判断                 | 说明                                                             |
| ------------------ | -------------------------------------------------------------- |
| `tier_count === 1` | **不要**渲染阶梯表；用 `rates` / `effective_rates`                      |
| `tier_count > 1`   | 有 `tiers[]`；`up_to_input_tokens` 为本档输入上界（含）；键不出现 = 不封顶（通常最后一档） |

阶梯语义：按**单次请求输入 token 总量**选一档，**整请求**按该档单价结算（不累进）。`tiers` 内是原价，乘 `price_factor` 得实付。

<Warning>
  `billing_type === "tiered_token"` **不能**用来判断是否多档——单档模型也可能是这个值。**只看 `tier_count`**。
</Warning>

## `limits`（与单价无关）

```json theme={null}
{
  "limits": {
    "max_input_tokens": 983616,
    "max_output_tokens": 131072,
    "supports_cache_read": true,
    "supports_cache_write": true
  }
}
```

* `supports_cache_read` / `supports_cache_write`：是否**支持**缓存能力；为 `false` 时即使 `rates` 有缓存价也不应展示为可用。
* `max_output_tokens`：请求未传 `max_tokens` 时的预扣上限参考，不是价格。

## TypeScript 类型（可直接用）

```ts theme={null}
type ToolItem = {
  unit: "usd_per_1000_queries" | "usd_per_page";
  price: number; // 原价，展示前 × price_factor
  precharge_queries?: number;
};

type Rates = {
  input?: number;
  cached_input?: number;
  explicit_cached_input?: number; // 缺省 ≈ 与 cached_input 同价
  cache_write?: number;
  cache_write_5m?: number;
  cache_write_1h?: number;
  output?: number;
  output_thinking?: number; // 缺省 = 仅一个输出价
  // pricing_mode === "image_modalities" 时另有 text_*/image_* 字段，勿与 standard 混读
  text_input?: number;
  cached_text_input?: number;
  image_input?: number;
  cached_image_input?: number;
  text_output?: number;
  image_output?: number;
};

type ModelPricing = {
  billing_type: string;
  source: "v1" | "v2";
  unit: "usd_per_million_tokens";
  pricing_mode: "standard" | "image_modalities";
  discount_rate: number;
  group: string;
  group_ratio: number;
  price_factor: number;
  resolved_from?: string;
  rates?: Rates;
  effective_rates?: Rates;
  tier_count: number;
  tiers?: (Rates & { up_to_input_tokens?: number })[];
  limits?: {
    max_input_tokens?: number;
    max_output_tokens?: number;
    supports_cache_read: boolean;
    supports_cache_write: boolean;
  };
  extras?: {
    tools?: Record<string, ToolItem>;
    google_web_search?: ToolItem;
  };
};
```

### 工具价渲染示例

```js theme={null}
const toolRows = Object.entries(pricing.extras?.tools ?? {}).map(
  ([tool, item]) => ({
    tool,
    actual: item.price * pricing.price_factor,
    suffix: item.unit === "usd_per_page" ? "/ 页" : "/ 千次调用",
    free: item.price === 0,
  }),
);
```

## 常见错法

| 错误                              | 正确                                            |
| ------------------------------- | --------------------------------------------- |
| 读 `token_price`                 | 读 `pricing.rates` / `pricing.effective_rates` |
| 自己 `rates × group_ratio`        | 直接用 `effective_rates`                         |
| 工具价直接展示 `extras.tools[x].price` | **× `price_factor`** 后再展示                     |
| 工具后缀写死「每千次」                     | 按 `item.unit` 判断                              |
| 缺省字段当 0 / 免费                    | 缺省 = **不适用**；只有显式 `0` 才是免费                    |
| 用 `billing_type` 判多档            | 用 `tier_count > 1`                            |
| 单档去读 `tiers`                    | 单档用 `rates`                                   |
| `pricing_mode` 混读字段             | `standard` 与 `image_modalities` 字段互斥          |

## 请求示例

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/api/pricing/model?model=qwen3.8-max' \
  --header 'Accept: application/json'
```

```python theme={null}
import requests

url = "https://api.apimart.ai/api/pricing/model"
params = {"model": "qwen3.8-max"}
headers = {"Accept": "application/json"}
print(requests.get(url, params=params, headers=headers).json())
```