A compact OpenAPI 3.1 reference for providers implementing the hvoy.ai pricing endpoint.
If a provider enables signature verification, calculate hex(HMAC-SHA256(auth_secret, X-Hvoy-Ts)). Timestamp skew must be within 60 seconds.
可选。hvoy 抓取时间戳（Unix 秒）。如果站点启用了签名校验，则必需，且与当前时间差不得超过 60 秒。
可选。`hex(HMAC-SHA256(auth_secret, X-Hvoy-Ts))`。如果站点启用了签名校验，则必需。
| Field | Type | Rule | Example | Description |
|---|---|---|---|---|
| currency | string | Required | "CNY" | 币种。当前协议固定为 `CNY`。 |
| price_unit | string | Required | "per_1m_tokens" | 价格单位。当前协议固定为 `per_1m_tokens`。 |
| site_name | string | Optional | "hvoy" | 站点名称，用于后台排查和展示。 |
| site_domain | string | Optional | "hvoy.ai" | 站点域名，用于来源追踪。 |
| updated_at | string | Required | "2026-04-22T12:00:00Z" | 本批价格数据的生成时间或最后更新时间。必须带时区信息，推荐使用 UTC 的 ISO 8601，例如 `2026-04-22T12:00:00Z`。 |
| models | array | Required | 价格列表。每一项代表一个 `model + group` 组合。 |
| Field | Type | Rule | Example | Description |
|---|---|---|---|---|
| model_name | string | Required | "claude-sonnet-4-6" | 模型稳定标识。机器匹配用 ID，不是展示名。 |
| group_name | string | Required | "cc" | 分组稳定标识。机器匹配用 ID，不是展示名。对外发布后不应频繁改名；改名会导致原 group 下线，并需要重新抓取，预计约 6 小时后重新进入排行榜。 |
| input_price | number | Required | 7.5 | 输入价格，单位为 `CNY / 1M tokens`。 |
| output_price | number | null | Optional | 37.5 | 输出价格，单位为 `CNY / 1M tokens`。如果不提供，可传 `null`。 |
| cache_input_price | number | null | Optional | 0.75 | 缓存读价格，单位为 `CNY / 1M tokens`。Claude 场景下应填 cache hits and refreshes，GPT 场景下通常对应 cached input。 |
| cache_create_price | number | null | Optional | 9.375 | 缓存写入价格，单位为 `CNY / 1M tokens`。如果只有单档写价填这里；Claude 场景下应填 5-minute cache writes。 |
| cache_create_price_1h | number | null | Optional | 15 | 1 小时缓存写入价格，单位为 `CNY / 1M tokens`。Claude 场景下应填 1-hour cache writes；其他服务商通常可传 `null`。 |
| enabled | boolean | Optional | true | 该 `model + group` 当前是否可售。缺失时抓取方默认按 `true` 处理。若某个组合未出现在返回列表中，抓取方应视为未匹配，不应自动推断为下线。 |
| note | string | Optional | "活动价" | 附加说明，不参与价格计算。 |
{
"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": ""
}
]
}
}