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

# 模型价格查询

> 查询可用模型、分组折扣、模型原价和支持的端点

## 接口信息

| 项目 | 说明 |
| - | - |
| 服务域名 | `https://maas.gravitex.ai/prod-api` |
| 数据格式 | `application/json` |
| 字符编码 | `UTF-8` |
| 协议 | `HTTPS`（强制） |
| 金额币种 | `USD`（美元） |

此接口没有请求参数，只需携带认证头。

## 1. 认证

所有请求都必须在 HTTP Header 中携带 Bearer 凭证。**支持两种凭证，任选其一**：

| 凭证类型 | 获取位置 | 查询范围 |
| - | - | - |
| 系统访问令牌（Access Token） | 控制台「个人设置 → 系统访问令牌」 | 整个账号 |
| API 密钥（API Key） | 控制台「令牌管理」，通常以 `sk-` 开头 | 仅这把密钥 |

| 字段 | 必填 | 说明 |
| - | - | - |
| `Authorization` | 是 | 格式为 `Bearer <凭证>`，填入上述任一凭证即可 |

```http theme={null}
# 方式一：系统访问令牌
Authorization: Bearer <access_token>

# 方式二：API 密钥
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```

以下情况视为认证失败：凭证缺失或错误、凭证已删除或禁用、账号已禁用。

***

## 2. 通用响应结构

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `code` | integer | 业务状态码，`200` 表示成功 |
| `msg` | string | 提示信息 |
| `data` | object | 业务数据；失败时为 `null` |

### 业务状态码

| code | 说明 |
| - | - |
| 200 | 成功 |
| 401 | 认证失败（凭证缺失、无效或已禁用） |

> 请以响应体中的 `code` 判断请求是否成功。

### 金额格式

* 所有金额都以\*\*美元（USD）\*\*表示，类型为 **string**，避免浮点精度丢失。
* 余额类金额**固定保留 4 位小数**，例如 `"986.9275"`。
* 模型单价**按实际价格输出，不补末尾的 0**，例如 `"40"`、`"2.5"`、`"0.00075"`。

***

## 3. 模型价格查询

```
GET /api/account/pricing
```

### 3.1 两种凭证的查询范围

| 凭证 | 返回的分组 | 返回的模型 |
| - | - | - |
| 系统访问令牌 | 账号可用的全部分组 | 账号可用分组下的全部模型 |
| API 密钥 | 仅该密钥所属分组 | 仅该密钥分组下的模型；如果密钥开启了模型限制，只返回限制内的模型 |

### 3.2 data 字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `currency` | string | 固定为 `USD` |
| `tokenUnit` | string | 固定为 `million`，表示 token 类单价都是「每百万 token」的价格 |
| `groups` | object\[] | 可用分组及折扣，见 3.3 |
| `supportedEndpoint` | object | 本次返回的模型所支持的端点类型及请求路径，见 3.4 |
| `models` | object\[] | 可用模型及价格，见 3.5 |
| `tokenName` | string | 仅使用 API 密钥时返回，表示当前密钥名称 |

### 3.3 groups：分组与折扣

| 字段 | 类型 | 说明 |
| - | - | - |
| `group` | string | 分组标识 |
| `desc` | string | 分组说明 |
| `ratio` | number | 分组倍率，也就是**折扣**；例如 `0.86` 表示按原价的 86% 计费 |

> `auto` 分组按实际命中的分组计费，它的 `ratio` 仅供参考。

### 3.4 supportedEndpoint：端点类型

键为端点类型，值为该类型对应的请求方式和路径，例如：

```json theme={null}
{
  "openai":          { "method": "POST", "path": "/v1/chat/completions" },
  "anthropic":       { "method": "POST", "path": "/v1/messages" },
  "openai-response": { "method": "POST", "path": "/v1/responses" },
  "gemini":          { "method": "POST", "path": "/v1beta/models/{model}:generateContent" }
}
```

只包含本次返回的模型用到的端点类型。每个模型的 `supportedEndpointTypes` 列出它支持哪些端点类型，可以在这里查到对应的请求路径。

### 3.5 models：模型与价格

| 字段 | 类型 | 说明 |
| - | - | - |
| `modelName` | string | 模型名称，调用时 `model` 参数填这个值 |
| `vendorName` | string | 模型供应商 |
| `billingType` | integer | 计费类型，见 3.8 |
| `enableGroups` | string\[] | 该模型可以在哪些分组下调用 |
| `supportedEndpointTypes` | string\[] | 支持的端点类型，对应 `supportedEndpoint` |
| `billingMode` | string | 仅阶梯计费模型返回，固定为 `tiered_expr` |
| `tierBasis` | string\[] | 仅阶梯计费模型返回，表示按什么划分阶梯，见 3.7 |
| `prices` | object | 模型**原价**，键为价格项、值为单价，见 3.6 |
| `pricingConfig` | object | 仅部分图像、视频、全模态模型返回，为该模型的详细计费配置，见 3.8 |

### 3.6 prices：价格项说明

**按 token 计费**（单位：USD / 百万 token）：

| 价格项 | 含义 |
| - | - |
| `textInputTokens` | 文本输入 |
| `textOutputTokens` | 文本输出 |
| `cacheTokens` | 缓存读取（缓存命中） |
| `cacheCreationTokens5m` | 缓存写入（5 分钟） |
| `cacheCreationTokens1h` | 缓存写入（1 小时） |
| `imageInputTokens` | 图片输入 |
| `imageOutputTokens` | 图片输出 |
| `audioInputTokens` | 音频输入 |
| `audioOutputTokens` | 音频输出 |
| `videoInputTokens` | 视频输入 |
| `videoOutputTokens` | 视频输出 |

**按次、按秒、按张计费**：

| 价格项 | 单位 |
| - | - |
| `perRequest` | USD / 次 |
| `seconds` | USD / 秒 |
| `imageCount` | USD / 张 |

**阶梯计费的价格项**：在上面的价格项后加上档位后缀。文本输入的价格项会省略 `text` 前缀，写作 `inputTokens`。

| 后缀 | 含义 | 示例 |
| - | - | - |
| `Lte` | 小于等于 | `inputTokensLte272K`：不超过 272K 时的输入单价 |
| `Lt` | 小于 | `inputTokensLt200K` |
| `Gte` | 大于等于 | `inputTokensGte200K` |
| `Gt` | 大于 | `textOutputTokensGt272K`：超过 272K 时的输出单价 |
| 区间 | 下限在前、上限在后 | `inputTokensGt32KLte128K`：大于 32K 且不超过 128K |
| `Peak` / `OffPeak` | 高峰时段 / 非高峰时段 | `inputTokensPeak`、`inputTokensOffPeak` |

数量单位：`K` 表示千 token，`M` 表示百万 token。例如 `272K` 表示 272,000 token，`1M` 表示 1,000,000 token。

### 3.7 tierBasis：阶梯划分依据

同样是 `Lte272K`，不同模型判断档位时看的数量可能不同，`tierBasis` 用来说明依据是什么：

| tierBasis | 含义 | 判断档位时统计的数量 |
| - | - | - |
| `context` | 按**上下文长度** | 本次请求的输入上下文总长度，**包含**缓存命中的部分 |
| `input` | 按**输入** | 本次请求的文本输入 token，**不包含**缓存、图片、音频等单独计价的部分 |
| `output` | 按**输出** | 本次请求的输出 token |
| `time` | 按**时段** | 请求发生的时间（北京时间） |

**计费规则**：

1. **整次请求按一个档位计费**：先根据本次请求的数量确定档位，然后这次请求的输入、输出、缓存等**全部按该档位的单价**计费，不分段累进。
   * 例：某模型 `tierBasis = ["context"]`，一次请求的上下文为 300K，命中 `Gt272K` 档，则这次请求的输入、输出、缓存都按 `xxxGt272K` 的单价计费。
2. **按上下文长度和按输入的区别在于缓存**：
   * 例：一次请求包含 200K 新输入和 100K 缓存命中。按上下文长度统计为 300K，命中 `Gt272K`；按输入统计只有 200K，命中 `Lte272K`。
3. **多个依据同时出现**（如 `["input", "output"]`）时，需要同时满足各项条件才命中对应档位。
4. **按时段计费**有两种形式：
   * `prices` 中同时给出 `xxxPeak` 和 `xxxOffPeak` 两组价格，分别对应高峰和非高峰时段。
   * `prices` 中只给出基础价，高峰时段在基础价上乘以系数。具体时段和系数请咨询客户经理。

### 3.8 billingType：计费类型

| billingType | 含义 | prices | pricingConfig |
| - | - | - | - |
| 0 | 按 token 计费 | token 类价格项，阶梯模型带档位后缀 | 无 |
| 1 | 按次计费 | `perRequest` | 无 |
| 2 | 图像按 token 计费 | 空 | 图像各项 token 单价（USD / 百万 token） |
| 3 | 视频按秒计费 | 统一单价时为 `seconds` | 按分辨率、是否含音频等区分价格时，在这里给出 |
| 4 | 全模态计费 | 空 | 文本、图像、音频等各项单价 |
| 5 | 按张计费 | 统一单价时为 `imageCount` | 按参考图数量、输出尺寸等区分价格时，在这里给出 |
| 6 | 视频按 token 计费 | token 类价格项（含 `videoOutputTokens`） | 按分辨率、是否含视频输入等区分价格时，在这里给出 |

> `pricingConfig` 的结构因模型而异，请以实际返回为准。

### 3.9 实际单价计算

```
实际单价 = prices 中的原价 × 所用分组的 ratio
```

例：使用 `ratio = 0.86` 的分组调用某模型，该模型 `textInputTokens` 为 `"8"`，则实际输入单价为 8 × 0.86 = **\$6.88 / 百万 token**。

### 3.10 响应示例

以下示例只截取了部分内容：

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "currency": "USD",
    "tokenUnit": "million",
    "groups": [
      { "group": "default",   "desc": "默认分组",  "ratio": 1.0 },
      { "group": "auto",      "desc": "自动",      "ratio": 1.0 },
      { "group": "Anthropic", "desc": "Anthropic", "ratio": 0.86 }
    ],
    "supportedEndpoint": {
      "openai":          { "method": "POST", "path": "/v1/chat/completions" },
      "anthropic":       { "method": "POST", "path": "/v1/messages" },
      "openai-response": { "method": "POST", "path": "/v1/responses" }
    },
    "models": [
      {
        "modelName": "claude-fable-5-2",
        "vendorName": "Anthropic",
        "billingType": 0,
        "enableGroups": ["Anthropic", "default"],
        "supportedEndpointTypes": ["openai", "anthropic"],
        "prices": {
          "textInputTokens": "8",
          "textOutputTokens": "40",
          "cacheTokens": "0.2",
          "cacheCreationTokens5m": "10"
        }
      },
      {
        "modelName": "gpt-5.4",
        "vendorName": "OpenAI",
        "billingType": 0,
        "enableGroups": ["default"],
        "supportedEndpointTypes": ["openai", "openai-response"],
        "billingMode": "tiered_expr",
        "tierBasis": ["context"],
        "prices": {
          "inputTokensLte272K": "2.5",
          "textOutputTokensLte272K": "15",
          "cacheTokensLte272K": "0.25",
          "inputTokensGt272K": "5",
          "textOutputTokensGt272K": "22.5",
          "cacheTokensGt272K": "0.5"
        }
      },
      {
        "modelName": "grok-imagine-image",
        "vendorName": "xAI",
        "billingType": 1,
        "enableGroups": ["default"],
        "supportedEndpointTypes": ["openai-images"],
        "prices": { "perRequest": "0.02" }
      }
    ]
  }
}
```

使用 API 密钥调用时，`groups` 只包含该密钥的分组，`models` 也相应只包含该分组下可用的模型，另外会多返回一个 `tokenName` 字段。

***

## 4. 调用示例

```bash theme={null}
# 查询模型价格
curl -s "https://maas.gravitex.ai/prod-api/api/account/pricing" \
  -H "Authorization: Bearer <access_token>"
```

***

## 5. 注意事项

1. **数据刷新**：模型价格调整后，最长约 1 分钟生效。
2. **价格为原价**：`prices` 返回的是模型原价，实际扣费需乘以所用分组的 `ratio`。
3. **以实际扣费为准**：本接口用于查询和预估，最终费用请以账单为准。
4. **妥善保管凭证**：系统访问令牌可以查询整个账号的信息，请勿泄露；如果只需要查询某个密钥的额度，建议使用对应的 API 密钥调用。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.