hvoy.ai 第三方价格接口规范

文档目的

本文档定义一个统一的第三方价格接口，供 API 中转站对外实现，供 hvoy.ai 抓取价格数据。

更新时间: 2026-04-19 version: 1.0

接口定义

推荐路径：

GET /api/provider/pricing

返回 Content-Type：

application/json; charset=utf-8

协议原则

1. 接口返回的是最终价格，不是内部计费参数。
2. 价格单位统一为 CNY / 1M tokens。
3. 同一个模型在不同 group 下可以返回多条记录。
4. 抓取方使用 model_name + group_name 作为匹配键。
5. 不支持的价格项可以返回 null，不要返回字符串。
6. cache_input_price 表示缓存读价；cache_create_price 和 cache_create_price_1h 表示缓存写价。

可选安全签名

很多站点可以直接公开 GET /api/provider/pricing。

如果站点担心价格接口被外部长期抓取，可以开启 hvoy 的可选签名校验。这个能力是可选的：

• 没开启时，接口继续按公开 GET 提供
• 开启后，只接受带签名的 hvoy 抓取请求
• 如果价格可以公开, 就不需要这个字段

请求头

X-Hvoy-Ts: 1747886400
X-Hvoy-Sign: <hex signature>

签名算法

站点与 hvoy 线下协商一个 auth_secret。 上线前, 请联系我们同学分配一个

签名规则：

sign = hex(HMAC-SHA256(auth_secret, ts))

其中：

• ts 是 Unix 时间戳（秒）
• 有效期为 1 分钟

服务端验签逻辑

站点收到请求后：

1. 读取 X-Hvoy-Ts
2. 读取 X-Hvoy-Sign
3. 校验 ts 与当前服务器时间差不超过 60 秒
4. 用本地保存的 auth_secret 重新计算 hex(HMAC-SHA256(auth_secret, ts))
5. 比较结果是否一致，一致才放行

测试抓取默认 secret

hvoy 文档页的“抓取测试”功能会自动带签名头，并使用固定测试 secret：

hvoy_provider_pricing_test_secret_v1_20260522

建议站点在联调阶段先临时接受这个测试 secret，等正式接入后，再切换成自己独立的生产 auth_secret。

Claude 兼容性说明

参考 Claude 官方定价文档：

• Claude pricing

按下面映射：

• cache_input_price 等于 Claude 的 cache hits and refreshes。
• cache_create_price 作为通用“缓存写入价”字段，在 Claude 场景下固定映射为 5-minute cache writes。
• cache_create_price_1h 用来补充 Claude 的 1-hour cache writes。

对非 Claude 或只有单档缓存写价的站点：

• 如果只有一个 cache write price，就填 cache_create_price
• cache_create_price_1h 填 null
• 如果根本不支持缓存，3 个缓存字段都填 null

标准返回结构

{
  "schema_version": "1.0",
  "success": true,
  "message": "",
  "data": {
    "currency": "CNY",
    "price_unit": "per_1m_tokens",
    "site_name": "hvoy",
    "site_domain": "hvoy.ai",
    "updated_at": "2026-04-22T12:00:00Z",
    "models": [
      {
        "model_name": "claude-sonnet-4-6",
        "group_name": "cc",
        "input_price": 7.5,
        "output_price": 37.5,
        "cache_input_price": 0.75,
        "cache_create_price": 9.375,
        "cache_create_price_1h": 15,
        "enabled": true,
        "note": ""
      }
    ]
  }
}

字段说明

顶层字段

data 字段

data.models[] 字段

字段含义与示例

schema_version

表示当前返回遵循的协议版本。

要求：

• 必须返回
• 当前固定为 "1.0"
• 本次新增字段不改变版本号

示例：

• "1.0"

success

表示接口本次是否成功返回价格数据。

示例：

• true
• false

message

用于返回错误原因或补充说明。

示例：

• ""
• "service temporarily unavailable"

data.currency

表示价格币种。当前协议建议固定为人民币。

示例：

• "CNY"

data.price_unit

表示价格单位。当前协议建议固定为每 100 万 tokens 的价格。

示例：

• "per_1m_tokens"

data.site_name

站点名称，主要用于展示和排查。

示例：

• "hvoy"

data.site_domain

站点域名，主要用于标识数据来源。

示例：

• "www.hvoy.ai"

data.updated_at

本批价格数据的更新时间，使用 ISO 8601 且必须带时区，例如 "2026-04-19T12:00:00Z"。

要求：

• 必须返回
• 表示当前这批价格数据的生成时间或最后更新时间
• 抓取方可据此判断价格是否过旧

示例：

• "2026-04-22T12:00:00Z"

data.models[].model_name

模型稳定标识，是抓取匹配的核心字段之一。

要求：

• 必须是稳定 ID，不是展示标题
• 不应返回中文展示名、营销名、带空格修饰的标题
• 一旦对外发布，不应频繁改名

示例：

• "claude-sonnet-4-6"
• "gpt-5.4"

data.models[].group_name

分组稳定标识，是抓取匹配的核心字段之一。

要求：

• 必须是稳定 ID，不是展示标题
• 建议使用站内真正的渠道 key
• 一旦对外发布，不应频繁改名. 改名后, 原来的group会下架, 需要重新抓取,预计要6个小时后进入排行榜.

示例：

• "cc"
• "codex"
• "default"

data.models[].input_price

输入价格，必须是最终价格，不应再要求抓取方换算。

示例：

• 7.5
• 1.25

data.models[].output_price

输出价格。如果不区分输入输出价格，可以传与 input_price 相同的值；如果不提供，可传 null。

示例：

• 37.5
• 7.5
• null

data.models[].cache_input_price

缓存读价格，不是缓存写价格。

兼容约束：

• 如果站点支持 cache read / cache hit 计价，这里填读价
• Claude 场景下，这里应填 cache hits and refreshes
• 如果不支持缓存读，传 null

示例：

• 0.75
• null

data.models[].cache_create_price

缓存写入价格。

兼容约束：

• 如果站点只有一个 cache write price，就填这里
• Claude 场景下，这里应填 5-minute cache writes
• 如果没有写缓存价格，传 null

示例：

• 9.375
• null

data.models[].cache_create_price_1h

1 小时缓存写入价格。

兼容约束：

• 仅当服务商存在单独的 1h cache write 定价时填写
• Claude 场景下，这里应填 1-hour cache writes
• 大多数非 Claude 服务商可直接传 null

示例：

• 15
• null

data.models[].enabled

表示该 model + group 当前是否可售。

语义约束：

• true 表示该组合当前可售
• false 表示该组合当前明确不可售或临时下线
• 如果字段缺失，抓取方默认按 true 处理
• 如果某个 model + group 组合根本没有出现在返回列表中，表示本接口未提供该组合价格，抓取方应视为未匹配，不应自动推断为下线

建议：

• 如果一个组合已知存在但当前下线，优先保留该记录并返回 enabled: false
• 不要通过直接删除该条记录来表达临时下线

示例：

• true
• false

data.models[].note

补充说明字段，不参与抓取逻辑。

示例：

• "活动价"
• "暂停售卖"

完整返回示例

{
  "schema_version": "1.0",
  "success": true,
  "message": "",
  "data": {
    "currency": "CNY",
    "price_unit": "per_1m_tokens",
    "site_name": "hvoy",
    "site_domain": "hvoy.ai",
    "updated_at": "2026-04-22T12:00:00Z",
    "models": [
      {
        "model_name": "claude-sonnet-4-6",
        "group_name": "cc",
        "input_price": 7.5,
        "output_price": 37.5,
        "cache_input_price": 0.75,
        "cache_create_price": 9.375,
        "cache_create_price_1h": 15,
        "enabled": true,
        "note": ""
      },
      {
        "model_name": "gpt-5.4",
        "group_name": "codex",
        "input_price": 1.25,
        "output_price": 7.5,
        "cache_input_price": 0.125,
        "cache_create_price": 0.5,
        "cache_create_price_1h": null,
        "enabled": true,
        "note": ""
      }
    ]
  }
}

失败返回示例

{
  "schema_version": "1.0",
  "success": false,
  "message": "service temporarily unavailable"
}

说明：

• 当 success=false 时，data 可以省略。
• 如果站点希望继续返回 data 作为调试信息，也可以保留，但抓取方不应依赖该行为。

抓取匹配规则

hvoy.ai 抓取时按以下方式匹配：

1. 读取 data.models 列表
2. 使用 model_name + group_name 匹配本地监控配置
3. 读取该条记录的：
   • input_price
   • output_price
   • cache_input_price
   • cache_create_price
   • cache_create_price_1h
   • enabled

因此第三方实现时应保证：

• model_name 是稳定 ID，不是展示名
• group_name 是稳定 ID，不是展示名
• 不同 model + group 组合不要重复。如果重复，抓取方只会取其中一条

未匹配语义：

• 如果接口中没有某个 model + group，抓取方应记为未匹配
• 未匹配不等于明确下线

数值约束

建议遵循以下约束：

• 所有价格字段应为 JSON number
• 不要返回字符串数字，例如 "7.5"
• 价格不得为负数
• 缺失值使用 null，不要使用空字符串
• 建议保留 2 到 6 位小数

最小可用实现

如果第三方只想先实现一个最小版本，最少可返回：

{
  "schema_version": "1.0",
  "success": true,
  "data": {
    "currency": "CNY",
    "price_unit": "per_1m_tokens",
    "updated_at": "2026-04-22T12:00:00Z",
    "models": [
      {
        "model_name": "claude-sonnet-4-6",
        "group_name": "cc",
        "input_price": 7.5,
        "output_price": 7.5
      }
    ]
  }
}

建议后续补充：

• cache_input_price
• cache_create_price
• cache_create_price_1h
• enabled
• note