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

文档目的

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

更新时间: 2026-06-19 version: 1.1

接口定义

推荐路径：

GET /api/provider/pricing

返回 Content-Type：

application/json; charset=utf-8

协议原则

1. 接口返回的是最终价格，不是内部计费参数。
2. 1.0 只支持 Token 计费；1.1 新增模型级计费单位，允许同一个响应里同时返回 Token 计费和按次计费。
3. 同一个模型在不同 group 下可以返回多条记录。
4. 抓取方使用 model_name + group_name 作为匹配键，不会跨 group 自动兜底匹配。
5. 不支持的价格项可以返回 null，不要返回字符串。
6. cache_input_price 表示缓存读价；cache_create_price 和 cache_create_price_1h 表示缓存写价。

版本兼容

1.0

1.0 只支持 Token 计费：

• schema_version 固定为 "1.0"
• data.price_unit 固定为 "per_1m_tokens"
• 每条 models[] 必须返回 input_price
• cache 字段可选，不支持时传 null

1.1

1.1 兼容 1.0 的 Token 计费，并新增按次计费：

• schema_version 可以返回 "1.1"
• data.price_unit 是默认计费单位，支持：
  • "per_1m_tokens"：按 Token 计费，单位为 CNY / 1M tokens
  • "per_call"：按次计费，单位为 CNY / 次
• 每条 models[] 可以返回自己的 price_unit 覆盖 data.price_unit
• 如果某条 models[] 没有返回 price_unit，抓取方使用 data.price_unit
• 当某条模型的最终 price_unit = "per_call" 时，使用 unit_price 表示单次调用价格
• 当某条模型的最终 price_unit = "per_call" 时，不需要返回 input_price、output_price、cache_input_price、cache_create_price、cache_create_price_1h
• 因此同一个响应里可以同时包含按 Token 计费的模型和按次计费的模型

可选安全签名

很多站点可以直接公开 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.1",
  "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-image-2",
        "group_name": "sora",
        "price_unit": "per_call",
        "unit_price": 0.2,
        "enabled": true,
        "note": ""
      }
    ]
  }
}

说明：

• data.price_unit 是默认值，上例默认 per_1m_tokens
• 第一条模型没有自己的 price_unit，所以按 per_1m_tokens 解析
• 第二条模型设置了 price_unit: "per_call"，所以按次解析，读取 unit_price

全部按次计费返回示例

适用于图片、视频、语音等按调用次数计费的模型。例如每次调用 0.2 元：

{
  "schema_version": "1.1",
  "success": true,
  "message": "",
  "data": {
    "currency": "CNY",
    "price_unit": "per_call",
    "site_name": "hvoy",
    "site_domain": "hvoy.ai",
    "updated_at": "2026-06-19T12:00:00Z",
    "models": [
      {
        "model_name": "gpt-image-2",
        "group_name": "sora",
        "unit_price": 0.2,
        "enabled": true,
        "note": ""
      }
    ]
  }
}

字段说明

顶层字段

data 字段

data.models[] 字段

字段含义与示例

schema_version

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

要求：

• 必须返回
• 旧版 Token 计费接口可以继续返回 "1.0"
• 新增按次计费或模型级 price_unit 时返回 "1.1"

示例：

• "1.0"
• "1.1"

success

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

示例：

• true
• false

message

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

示例：

• ""
• "service temporarily unavailable"

data.currency

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

示例：

• "CNY"

data.price_unit

表示默认价格单位。每条 models[] 可以用自己的 price_unit 覆盖。

示例：

• "per_1m_tokens"
• "per_call"

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

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

兼容约束：

• 当最终 price_unit = "per_1m_tokens" 时必需
• 当最终 price_unit = "per_call" 时不需要传

示例：

• 7.5
• 1.25

data.models[].price_unit

当前模型/分组的价格单位。不传时继承 data.price_unit。

示例：

• "per_1m_tokens"
• "per_call"

data.models[].unit_price

按次调用价格，必须是最终价格，不应再要求抓取方换算。

兼容约束：

• 当最终 price_unit = "per_call" 时必需
• 当最终 price_unit = "per_1m_tokens" 时不需要传
• 单位为 CNY / 次

示例：

• 0.2
• 1

data.models[].output_price

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

当最终 price_unit = "per_call" 时，不需要传该字段。

示例：

• 37.5
• 7.5
• null

data.models[].cache_input_price

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

兼容约束：

• 当最终 price_unit = "per_call" 时，不需要传该字段
• 如果站点支持 cache read / cache hit 计价，这里填读价
• Claude 场景下，这里应填 cache hits and refreshes
• 如果不支持缓存读，传 null

示例：

• 0.75
• null

data.models[].cache_create_price

缓存写入价格。

兼容约束：

• 当最终 price_unit = "per_call" 时，不需要传该字段
• 如果站点只有一个 cache write price，就填这里
• Claude 场景下，这里应填 5-minute cache writes
• 如果没有写缓存价格，传 null

示例：

• 9.375
• null

data.models[].cache_create_price_1h

1 小时缓存写入价格。

兼容约束：

• 当最终 price_unit = "per_call" 时，不需要传该字段
• 仅当服务商存在单独的 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.1",
  "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": ""
      },
      {
        "model_name": "gpt-image-2",
        "group_name": "sora",
        "price_unit": "per_call",
        "unit_price": 0.2,
        "enabled": true,
        "note": ""
      }
    ]
  }
}

失败返回示例

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

说明：

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

抓取匹配规则

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

1. 读取 data.models 列表
2. 使用 model_name + group_name 匹配本地监控配置
3. 计算该条记录的最终计费单位：
   • 如果 models[].price_unit 有值，使用 models[].price_unit
   • 否则使用 data.price_unit
4. 按最终计费单位读取价格字段：
   • per_1m_tokens：读取 input_price、output_price、cache_input_price、cache_create_price、cache_create_price_1h
   • per_call：读取 unit_price
5. 读取该条记录的：
   • enabled

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

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

未匹配语义：

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

数值约束

建议遵循以下约束：

• 所有价格字段应为 JSON number
• 不要返回字符串数字，例如 "7.5"
• 价格不得为负数
• 缺失值使用 null，不要使用空字符串
• 建议保留 2 到 6 位小数
• per_call 模式下 unit_price 不得为 0；临时免费或下线请使用 enabled: false 或不返回该组合

最小可用实现

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

{
  "schema_version": "1.1",
  "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
      }
    ]
  }
}

按次计费的最小版本：

{
  "schema_version": "1.1",
  "success": true,
  "data": {
    "currency": "CNY",
    "price_unit": "per_1m_tokens",
    "updated_at": "2026-06-19T12:00:00Z",
    "models": [
      {
        "model_name": "gpt-image-2",
        "group_name": "sora",
        "price_unit": "per_call",
        "unit_price": 0.2
      }
    ]
  }
}

建议后续补充：

• cache_input_price
• cache_create_price
• cache_create_price_1h
• enabled
• note