模型与价格查询接口

概述

/v1/models/pricing 是一个公开匿名的聚合接口，输出平台当前可用的所有模型及其对外公示价。响应严格遵循 OpenRouter Providers 规范，同时也可被任意第三方平台或客户端程序化抓取。

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

适用场景

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

接口定义

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

请求示例

curl https://api.ephone.ai/v1/models/pricing

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"])

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 })));

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 数组包裹：

{
  "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` 元素使用，标识触发该层定价的最小上下文长度

缺省的字段在响应中可能直接返回 "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 搜索工具

三种计费模式的映射

平台支持三种计费模式（详见产品定价），全部能映射到 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 则保持不变
不包含：代理商加价、用户等级折扣、用户专属倍率、时间段倍率、运行时动态因子

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

分层定价

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

{
  "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`	OpenAI SDK 兼容的模型 ID 列表	需 Token
`/api/pricing`	前端价格页（带用户上下文）	可选 Token

常见问题

为什么返回的价格和我实际付费的不一样？

公示价是匿名场景下「默认分组」的最终成交价。如果你属于其它分组（如 pro / premium）、有等级折扣、或在代理商域名下访问，实际付费会有差异。登录后请通过 /api/pricing 查询你自己的真实价格。

为什么某些字段是 '0'？

"0" 在协议中既可能表示「免费」也可能表示「该模型不支持此维度」。建议结合 supported_features 与 supported_sampling_parameters 判断模型能力，不要仅凭 pricing 字段推断功能支持情况。

按秒计费的模型（TTS / Realtime / 视频）如何换算？

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

抓取频率有限制吗？

接口有每 IP 严格限流。建议：

抓取频率不高于每 5 分钟一次
利用响应头 Cache-Control: max-age=60 做客户端缓存
长期监控可订阅平台公告渠道，而非高频轮询

可以筛选 vendor / modality 吗？

当前接口不支持过滤参数，始终返回全部正常状态的模型。客户端可在拿到 data 数组后自行按 supported_features / input_modalities 等字段过滤。

开始使用

模型与服务

使用指南

模型与价格查询接口

概述

适用场景

接口定义

请求示例

响应结构

顶层字段

Model 对象字段

Pricing 对象字段

supported_features 枚举

三种计费模式的映射

价格计算说明

分层定价

数据来源：结构化 Prompt Tiers

切档维度

匹配规则

不支持公示的分层维度

数据更新与缓存

与其它接口的区别

常见问题

​概述

​适用场景

​接口定义

​请求示例

​响应结构

​顶层字段

​Model 对象字段

​Pricing 对象字段

​supported_features 枚举

​三种计费模式的映射

​价格计算说明

​分层定价

​数据来源：结构化 Prompt Tiers

​切档维度

​匹配规则

​不支持公示的分层维度

​数据更新与缓存

​与其它接口的区别

​常见问题

概述

适用场景

接口定义

请求示例

响应结构

顶层字段

Model 对象字段

Pricing 对象字段

supported_features 枚举

三种计费模式的映射

价格计算说明

分层定价

数据来源：结构化 Prompt Tiers

切档维度

匹配规则

不支持公示的分层维度

数据更新与缓存

与其它接口的区别

常见问题