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

# 模型与价格查询接口

> 公开匿名的模型清单与公示价聚合接口，遵循 OpenRouter Providers 规范，可被第三方价格聚合平台或客户端程序化抓取。

## 概述

`/v1/models/pricing` 是一个**公开匿名**的聚合接口，输出平台当前可用的所有模型及其对外公示价。响应严格遵循 [OpenRouter Providers 规范](https://openrouter.ai/docs/guides/community/for-providers)，同时也可被任意第三方平台或客户端程序化抓取。

> [!NOTE]
>
> 该接口是「对外公示价」入口，不带任何用户身份。返回的价格是默认分组（`default`）的最终成交价（USD），与匿名抓取场景一致。登录后的真实付费价请使用 [`/api/pricing`](https://docs.rixapi.com/docs/cn/guides/pricing)（携带用户分组、等级折扣等上下文）。

## 适用场景

| 场景 | 说明 |
| - | - |
| 第三方价格聚合 | OpenRouter、其它聚合站抓取本平台模型清单与公示价 |
| 客户端展示 | 第三方应用、Bot、SDK 需展示可用模型列表 |
| 监控告警 | 用于监控本平台模型 / 价格的变更 |

## 接口定义

| 项 | 值 |
| - | - |
| **URL** | `https://api.ephone.ai/v1/models/pricing` |
| **方法** | `GET` |
| **鉴权** | 无（公开匿名） |
| **限流** | 每 IP 严格限流（CriticalRateLimit） |
| **缓存** | 进程内 60 秒缓存；响应附 `Cache-Control: public, max-age=60` |

### 请求示例

```bash cURL theme={null}
curl https://api.ephone.ai/v1/models/pricing
```

```python Python theme={null}
import requests

resp = requests.get("https://api.ephone.ai/v1/models/pricing", timeout=10)
data = resp.json()["data"]
for m in data[:3]:
    print(m["id"], m["pricing"])
```

```javascript Node.js theme={null}
const resp = await fetch("https://api.ephone.ai/v1/models/pricing");
const { data } = await resp.json();
console.log(data.slice(0, 3).map(m => ({ id: m.id, pricing: m.pricing })));
```

```go Go theme={null}
package main

import (
    "encoding/json"
    "net/http"
)

type ModelEntry struct {
    ID      string                 `json:"id"`
    Name    string                 `json:"name"`
    Pricing map[string]interface{} `json:"pricing"`
}

func main() {
    resp, _ := http.Get("https://api.ephone.ai/v1/models/pricing")
    defer resp.Body.Close()
    var body struct{ Data []ModelEntry }
    _ = json.NewDecoder(resp.Body).Decode(&body)
    _ = body
}
```

## 响应结构

顶层结构始终用 `data` 数组包裹：

```json theme={null}
{
  "data": [
    {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "created": 1715558400,
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "quantization": "unknown",
      "context_length": 128000,
      "max_output_length": 16384,
      "pricing": {
        "prompt": "0.0000025",
        "completion": "0.00001",
        "request": "0",
        "image": "0",
        "input_cache_read": "0.00000125"
      },
      "supported_sampling_parameters": [
        "temperature", "top_p", "frequency_penalty", "presence_penalty",
        "stop", "seed", "max_tokens", "logit_bias", "response_format",
        "tools", "tool_choice", "parallel_tool_calls", "logprobs", "top_logprobs"
      ],
      "supported_features": ["tools", "json_mode", "structured_outputs", "logprobs"]
    }
  ]
}
```

### 顶层字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `data` | `Array<Model>` | 模型条目数组；空数组表示当前无可对外公示的模型 |

### Model 对象字段

| 字段 | 类型 | 必选 | 说明 |
| - | - | - | - |
| `id` | `string` | ✅ | 模型唯一标识，调用 `/v1/chat/completions` 时使用该值 |
| `name` | `string` | ✅ | 显示名称（如 `GPT-4o`），未配置时回退为 `id` |
| `created` | `int64` | ✅ | 模型发布时间（Unix 秒） |
| `input_modalities` | `string[]` | ✅ | 支持的输入模态，至少包含 `text` |
| `output_modalities` | `string[]` | ✅ | 支持的输出模态，至少包含 `text` |
| `quantization` | `string` | ✅ | 量化方式（`fp16` / `fp8` / `bf16` / `int8` / `unknown`） |
| `context_length` | `int` | ✅ | 上下文窗口最大 token 数 |
| `max_output_length` | `int` | ✅ | 单次响应最大输出 token 数 |
| `pricing` | `Pricing` | ✅ | 定价对象，详见下方 |
| `pricing_tiers` | `Pricing[]` | | 分层定价数组（最多 1 个元素，由管理员显式标注阈值后输出） |
| `supported_sampling_parameters` | `string[]` | ✅ | 支持的采样参数（如 `temperature`、`top_p` 等） |
| `supported_features` | `string[]` | ✅ | 支持的功能枚举（见下方表） |
| `deprecation_date` | `string` | | 计划废弃日期（ISO 8601, `YYYY-MM-DD`） |
| `hugging_face_id` | `string` | | 开源模型对应 Hugging Face 仓库 ID |

### Pricing 对象字段

所有价格以 **美元（USD）字符串** 表示。token 类字段单位为 `USD / token`，扁平类字段单位见说明列。

| 字段 | 类型 | 必选 | 单位 | 说明 |
| - | - | - | - | - |
| `prompt` | `string` | ✅ | USD / input token | 输入 token 单价 |
| `completion` | `string` | ✅ | USD / output token | 输出 token 单价 |
| `request` | `string` | ✅ | USD / request | 每请求固定费用（按次模型使用） |
| `image` | `string` | ✅ | USD / image | 图像生成单价（按张） |
| `audio` | `string` | | USD / audio | 音频生成单价（按段） |
| `video` | `string` | | USD / video | 视频生成单价（按段） |
| `web_search` | `string` | | USD / query | 内置 Web 搜索工具调用单价 |
| `internal_reasoning` | `string` | | USD / reasoning token | 推理 token 单价（o1 / Claude thinking 系列） |
| `input_cache_read` | `string` | | USD / token | 缓存命中读取单价 |
| `input_cache_write` | `string` | | USD / token | 缓存写入单价（取最贵窗口公示） |
| `min_context` | `int` | | tokens | **仅 `pricing_tiers` 元素使用**，标识触发该层定价的最小上下文长度 |

> [!NOTE]
>
> * 缺省的字段在响应中可能直接返回 `"0"`（基础四字段：`prompt` / `completion` / `request` / `image` 始终存在），或被省略（可选字段）
> * `"0"` 既可能代表「免费」也可能代表「该模型不支持此维度」；建议结合 `supported_features` 与 `supported_sampling_parameters` 综合判断

### supported\_features 枚举

| 值 | 含义 |
| - | - |
| `tools` | 支持工具调用（Function Calling） |
| `reasoning` | 支持推理过程（reasoning\_content / thinking） |
| `json_mode` | 支持 JSON 模式输出 |
| `structured_outputs` | 支持结构化输出（Schema 约束） |
| `logprobs` | 支持返回 token 对数概率 |
| `web_search` | 支持内置 Web 搜索工具 |

## 三种计费模式的映射

平台支持三种计费模式（详见 [产品定价](https://docs.rixapi.com/docs/cn/guides/pricing.md)），全部能映射到 OpenRouter 规范字段：

| 内部计费模式 | 输出字段 | 说明 |
| - | - | - |
| **按 Token** | `prompt` / `completion` / `internal_reasoning` / `input_cache_read` / `input_cache_write` / `web_search` | 文本类、Embedding 等模型；token 单价由「USD/百万 token」换算为「USD/token」 |
| **按次** | `image` / `video` / `audio` / `request` | 按单位类型自动路由；图像生成 → `image`，视频生成 → `video`，音乐/语音 → `audio`，其它 → `request` |
| **按秒** | `request` / `video` / `audio` | 按典型用例秒数（如 30 秒）换算为「每请求公示价」；**实际计费仍按真实秒数 × 单价**，对账不会偏移 |

## 价格计算说明

公示价计算公式：

```
final_usd = base_price × group_ratio × currency_factor
```

* **base\_price**：管理员后台配置的官方报价
* **group\_ratio**：默认分组（`default`）的分组倍率
* **currency\_factor**：若 base 配置为 CNY 则除以汇率换为 USD，配置为 USD 则保持不变
* **不包含**：代理商加价、用户等级折扣、用户专属倍率、时间段倍率、运行时动态因子

> [!WARNING]
>
> 登录用户的实际付费可能与公示价不同。如果用户属于其它分组、有等级折扣、或在代理商域名下访问，会有不同价格。匿名抓取只反映平台对外公示的基础价。

## 分层定价

某些模型在不同上下文长度区间有不同单价（如 Gemini 1.5 / 2.5 Pro 在 ≥128K 时翻倍）。这类模型的「高档价格」会通过 `pricing_tiers` 数组输出：

```json theme={null}
{
  "id": "gemini-1.5-pro",
  "pricing": {
    "prompt": "0.00000125",
    "completion": "0.000005",
    "request": "0",
    "image": "0"
  },
  "pricing_tiers": [
    {
      "min_context": 128000,
      "prompt": "0.0000025",
      "completion": "0.00001",
      "request": "0",
      "image": "0"
    }
  ]
}
```

* `pricing` 是基础层（PromptTiers 中阈值最低的那档）
* `pricing_tiers[i]` 是高档；当请求总输入 tokens ≥ `min_context` 时按此层计费
* 当前最多返回 **1 个高档**（与 OpenRouter 规范的最多 2 层一致）

### 数据来源：结构化 Prompt Tiers

平台后台为每个模型配置「Prompt Tiers」结构化分层。每档由两个字段构成：

| 字段 | 含义 |
| - | - |
| `min_prompt_tokens` | 触发阈值（含缓存与多模态 tokens） |
| `price` | 该档对应的完整 `PriceData`（input / output / cache / 多模态各自单价） |

**运行时计费与对外公示用同一份数据**——保证公示价 ≡ 实际计费价，OpenRouter 月度对账不会偏移。

### 切档维度

阈值匹配按 **「总输入 tokens」** 进行，**包含缓存与多模态**：

```
TotalPromptTokensForTier =
    纯文本输入
  + 文本缓存（cache_read / cache_create / 5m / 1h）
  + 图片输入 + 图片缓存读取
  + 音频输入 + 音频缓存读取
  + 视频输入 + 视频缓存读取
```

这与 OpenRouter `min_context` 及 Gemini / Claude 官方分层文档语义对齐——「按总上下文长度切档」，否则用户全走缓存就能绕过分层定价。

### 匹配规则

从大到小匹配：取满足 `total >= min` 的档中阈值最大的那档。**全量按命中档单价**计费（与官方厂商一致，不是阶梯递进）。

不命中任何档时走基础档（阈值最低那档）。

### 不支持公示的分层维度

OpenRouter 规范只能表达「按上下文 token 数」的单维度切档。对于以下场景，平台仍使用通用规则引擎（Conditions）计费，但**不会**通过 `pricing_tiers` 公示——OpenRouter 只看到基础价：

* 按图像质量切档（如 `request.body.quality == '1080p'`）
* 按视频时长切档（如 `request.body.duration > 30`）
* 按响应特征切档（如 `response.body.usage.reasoning_tokens > 100`）
* 复合条件（`&&` / `||` 组合）

如需让 OpenRouter 接入这类模型，建议为该模型在 `default` 分组下额外配置一份**无条件**价格作为公示基线。

## 数据更新与缓存

| 维度 | 说明 |
| - | - |
| **服务端缓存** | 进程内缓存 60 秒；管理员变更模型/价格后最多延迟 1 分钟生效 |
| **客户端缓存** | 响应附 `Cache-Control: public, max-age=60`，CDN 与浏览器可安全缓存 1 分钟 |
| **建议抓取频率** | ≥ 5 分钟一次；高频抓取会被限流 |

## 与其它接口的区别

| 接口 | 用途 | 鉴权 |
| - | - | - |
| **`/v1/models/pricing`** | **本接口**：对外公示价（OpenRouter 规范） | 公开 |
| [`/v1/models`](https://platform.openai.com/docs/api-reference/models/list) | OpenAI SDK 兼容的模型 ID 列表 | 需 Token |
| [`/api/pricing`](https://docs.rixapi.com/docs/cn/guides/pricing) | 前端价格页（带用户上下文） | 可选 Token |

## 常见问题

> [accordion] 为什么返回的价格和我实际付费的不一样？
>
> 公示价是匿名场景下「默认分组」的最终成交价。如果你属于其它分组（如 `pro` / `premium`）、有等级折扣、或在代理商域名下访问，实际付费会有差异。登录后请通过 [`/api/pricing`](https://docs.rixapi.com/docs/cn/guides/pricing) 查询你自己的真实价格。

> [accordion] 为什么某些字段是 '0'？
>
> `"0"` 在协议中既可能表示「免费」也可能表示「该模型不支持此维度」。建议结合 `supported_features` 与 `supported_sampling_parameters` 判断模型能力，不要仅凭 pricing 字段推断功能支持情况。

> [accordion] 按秒计费的模型（TTS / Realtime / 视频）如何换算？
>
> OpenRouter 规范不支持 `per_second` 字段，平台会按管理员配置的「典型用例秒数」（默认 30 秒）把 `每秒单价 × 秒数` 换算为 `request` / `video` / `audio` 字段的公示价。**实际计费始终按真实秒数 × 单价**，对账时不会因换算而少扣或多扣。

> [accordion] 抓取频率有限制吗？
>
> 接口有每 IP 严格限流。建议：
>
> * 抓取频率不高于每 5 分钟一次
> * 利用响应头 `Cache-Control: max-age=60` 做客户端缓存
> * 长期监控可订阅平台公告渠道，而非高频轮询

> [accordion] 可以筛选 vendor / modality 吗？
>
> 当前接口不支持过滤参数，始终返回全部正常状态的模型。客户端可在拿到 `data` 数组后自行按 `supported_features` / `input_modalities` 等字段过滤。


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