A compact OpenAPI 3.1 reference for providers implementing the hvoyai.com 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`、`per_call` 和 `per_second`（`per_call` / `per_second` 需要 `schema_version` 为 `1.1`）；单条模型可用 `models[].price_unit` 覆盖。 |
| site_name | string | Optional | "hvoy" | 站点名称，用于后台排查和展示。 |
| site_domain | string | Optional | "hvoyai.com" | 站点域名，用于来源追踪。 |
| 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 小时后重新进入排行榜。 |
| price_unit | string | Optional | "per_call" | 当前模型/分组的价格单位。不传时继承 `data.price_unit`。 |
| input_price | number | Optional | 7.5 | 输入价格，单位为 `CNY / 1M tokens`。最终 price_unit 为 `per_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`。 |
| unit_price | number | Optional | 0.2 | 按次或按秒价格，必须大于 0。最终 price_unit 为 `per_call` 时单位为 `CNY / 次`；为 `per_second` 时是 `billing_basis.resolution` 那一档的最终秒价，单位为 `CNY / 秒`，不含参考视频加价。最终 price_unit 为 `per_call` 或 `per_second` 时必需。 |
| billing_basis | object | Optional | {"resolution":"480p"} | 最终 price_unit 为 `per_second` 时必填。`resolution` 为该秒价对应的分辨率，请写成 `480p`、`720p`、`1080p` 这种形式；只能用字母、数字、`.`、`_`、`-`，最长 40 个字符，不区分大小写。参考档为 480p：提供 480p 时必须用 480p 报价，否则模型被忽略；没有 480p 时用最便宜的一档，传了 `variants` 时 `unit_price` 必须等于其中最低的秒价，否则模型被忽略。按秒计费只用于视频生成模型，非视频模型请不要使用 `per_second`，不要为了通过校验填写分辨率。 |
| variants | array | Optional | [{"resolution":"480p","unit_price":0.55,"ref_video_price":8.25},{"resolution":"720p","unit_price":1.15,"ref_video_price":17.25}] | 可选，仅 `per_second` 使用，最多 8 档，分辨率不能重复（不区分大小写）。每档包含 `resolution`、`unit_price`（CNY / 秒，>0）、`ref_video_price`（每条参考视频加价 CNY，可省略）。必须有一档与 `billing_basis.resolution` 相同且价格等于模型 `unit_price`，否则模型被忽略；`variants` 本身格式错误时只忽略 `variants`，模型价格保留。只有一档但有参考视频加价时，传一项 `variants`。其它清晰度会显示在首页和榜单价格旁的浮层里。 |
| enabled | boolean | Optional | true | 该 `model + group` 当前是否可售。缺失时抓取方默认按 `true` 处理。若某个组合未出现在返回列表中，抓取方应视为未匹配，不应自动推断为下线。 |
| note | string | Optional | "活动价" | 附加说明，不参与价格计算。 |
Protocol 1.1 supports per-second billing for video generation models only. Do not use per_second for non-video models, and do not fill in a resolution just to pass validation. data.price_unit is the default unit and may be per_1m_tokens, per_call or per_second; set price_unit on a model when that row uses a different unit. All three units may appear in one response. For per_call, unit_price is CNY per call. For per_second, unit_price is CNY per second. "1.0" supports neither per-call nor per-second billing.
billing_basis is required for per-second billing. Set billing_basis.resolution to the resolution this price applies to, such as 480p; the leaderboard and the model price page show it next to the price. unit_price is the final per-second price of that tier and excludes any reference-video charge. Do not put a per-second price in per_call, and do not explain the unit in note; note is not used for pricing.
The reference tier is 480p. If you offer 480p, quote unit_price for 480p and set billing_basis.resolution to 480p; a model priced on another tier is ignored. If you do not offer 480p, quote your cheapest tier; when you send variants, unit_price must equal the lowest per-second price among them, or the model is ignored.
Put other resolutions in variants, up to 8 tiers, without repeating a resolution. Each tier's unit_price is CNY per second; ref_video_price is an extra charge per reference video in CNY, omitted when there is none. One variant must match billing_basis.resolution with the same price as the model unit_price, or the model is ignored. If variants itself is malformed, only variants is ignored and the model price is kept. If there is only one tier but it has a reference-video charge, send a single-item variants. Other resolutions are shown in a popover next to the price on the home page and the leaderboard.
Write resolutions as 480p, 720p, 1080p and so on; a resolution may only contain letters, digits, ., _ and -, up to 40 characters, and is case-insensitive. Keep model_name as the stable id, for example doubao-seedance-2.5; do not encode resolution in it.
A row has one primary unit. When a model has both a per-call and a per-second price, send the per-second row. Video models that are actually billed per token stay on per_1m_tokens.
Keep the default unit as per_1m_tokens and override price_unit only on per-second models; if every model on the site is billed per second, you may set data.price_unit to per_second.
When we fetch your endpoint, each skipped or partially ignored model produces a warning in the form models[<i>] <code>:<model>/<group>. variants_dropped adds one more segment with the reason at the end.
| Code | Description |
|---|---|
| invalid_object | This item is not an object and was ignored. |
| missing_model_or_group | Missing model_name or group_name; ignored. |
| model_price_unit_requires_1.1 | Model-level price_unit is not allowed with schema_version "1.0"; ignored. Use "1.1" for per-call or per-second pricing. |
| unsupported_price_unit | Unsupported price_unit; ignored. Supported: per_1m_tokens, per_call, per_second. |
| duplicate_model_group | The same model_name + group_name appears more than once; only one of them is used. Remove the duplicates. |
| invalid_input_price | input_price is missing, not a number or negative; ignored. |
| zero_input_price_skipped | input_price is 0; ignored. |
| invalid_unit_price | unit_price is missing, not a number or negative; ignored. |
| zero_unit_price_skipped | unit_price is 0; ignored. |
| invalid_billing_basis | Per-second pricing requires billing_basis.resolution (letters, digits, ., _, -, up to 40 characters); ignored. Per-second billing is for video generation models only; do not use per_second for non-video models. |
| billing_basis_mismatch | variants has no tier matching billing_basis.resolution, or that tier's price differs from unit_price; ignored. |
| billing_basis_not_reference | variants includes 480p but the price is not quoted on 480p. Set unit_price to the 480p per-second price and billing_basis.resolution to 480p; ignored. |
| billing_basis_not_lowest | Without 480p, quote your cheapest tier; unit_price is not the lowest per-second price in variants; ignored. |
| variants_dropped | variants is malformed; only variants was ignored and the model price is kept. |
variants_dropped| Reason | Description |
|---|---|
| not_array | not an array |
| empty | is empty |
| too_many | has more than 8 tiers |
| invalid_item | a tier is not an object |
| invalid_resolution | a tier has an invalid resolution |
| invalid_unit_price | a tier has an invalid or non-positive unit_price |
| invalid_ref_video_price | a tier has an invalid or negative ref_video_price |
| duplicate_resolution | a resolution is repeated (case-insensitive) |
Use the fetch tester to check your endpoint and see these warnings with explanations.
{
"schema_version": "1.1",
"success": true,
"message": "",
"data": {
"currency": "CNY",
"price_unit": "per_1m_tokens",
"site_name": "hvoy",
"site_domain": "hvoyai.com",
"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": ""
},
{
"model_name": "doubao-seedance-2.5",
"group_name": "video",
"price_unit": "per_second",
"unit_price": 0.55,
"billing_basis": {
"resolution": "480p"
},
"variants": [
{
"resolution": "480p",
"unit_price": 0.55,
"ref_video_price": 8.25
},
{
"resolution": "720p",
"unit_price": 1.15,
"ref_video_price": 17.25
}
],
"enabled": true,
"note": ""
}
]
}
}