Provider Pricing API

Purpose

This document defines a unified third-party pricing API. AI API gateways implement it publicly, and hvoyai.com collects price data from it.

Last updated: 2026-10-13 version: 1.1

Revision history:

• 2026-10-13: 1.1 adds per_second (per-second billing, for video generation models only; do not use per_second for non-video models). Per-second prices use unit_price (CNY / second), billing_basis is required, and the reference tier is 480p. The version number remains 1.1.

Endpoint

Recommended path:

GET /api/provider/pricing

Response Content-Type:

application/json; charset=utf-8

Protocol principles

1. The API returns final prices, not internal billing parameters.
2. 1.0 supports token billing only. 1.1 adds a per-model billing unit, so a single response can mix token billing, per-call billing, and per-second billing.
3. The same model can return multiple records under different groups.
4. The collector matches records by model_name + group_name and never falls back to another group automatically.
5. Unsupported price items can be returned as null. Do not return strings.
6. cache_input_price is the cache read price. cache_create_price and cache_create_price_1h are cache write prices.
7. 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.

Version compatibility

1.0

1.0 supports token billing only:

• schema_version is always "1.0"
• data.price_unit is always "per_1m_tokens"
• Every models[] item must return input_price
• Cache fields are optional; return null when unsupported

1.1

1.1 keeps 1.0 token billing and adds per-call and per-second billing:

• schema_version can be "1.1"
• data.price_unit is the default billing unit. Supported values:
  • "per_1m_tokens": token billing, in CNY / 1M tokens
  • "per_call": per-call billing, in CNY / call
  • "per_second": per-second billing, in CNY / second
• Each models[] item can return its own price_unit to override data.price_unit
• If a models[] item does not return price_unit, the collector uses data.price_unit
• When an item's final price_unit = "per_call", unit_price is the price of one call; for per_second, unit_price is the price per second
• When an item's final price_unit is "per_call" or "per_second", you do not need to return input_price, output_price, cache_input_price, cache_create_price, or cache_create_price_1h
• When an item's final price_unit = "per_second", billing_basis is required
• A single response can therefore contain token-billed, per-call, and per-second models at the same time

Per-second billing

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 can be per_1m_tokens, per_call, or per_second. When one model needs a different unit, set that item's own price_unit. All three units can appear in the same price list. For per_call, unit_price is CNY per call; for per_second, unit_price is CNY per second. "1.0" cannot use per-call or per-second billing.

billing_basis is required for per-second billing. billing_basis.resolution is the resolution this per-second price applies to, for example 480p. The leaderboard and model price pages show it next to the price. unit_price is the final per-second price for that tier and excludes reference video surcharges. Do not put a per-second price under per_call, and do not rely on note to describe the unit; note is not used in price calculation.

The reference tier is 480p. If you offer 480p, you must quote unit_price at 480p and set billing_basis.resolution to 480p; models quoted at another tier are ignored. If you do not offer 480p, quote your cheapest tier. When variants is provided, unit_price must equal the lowest per-second price in it, otherwise the model is ignored.

Put other resolutions in variants, up to 8 tiers, with no duplicate resolutions. Each tier's unit_price is CNY per second. ref_video_price is the surcharge per reference video (CNY per video); omit it if there is none. variants must include a tier with the same resolution as billing_basis.resolution and a price equal to the model's unit_price, otherwise the model is ignored. If variants itself is malformed, only variants is dropped and the model price is kept. If you have only one tier but charge a reference video surcharge, pass a single variants item. 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. Only letters, digits, ., _, and - are allowed, up to 40 characters, case-insensitive. Keep the model name as a stable ID, for example doubao-seedance-2.5, and do not put the resolution in model_name.

Each record has exactly one primary unit. If the same model has both a per-call price and a per-second price, submit the per-second record. Video models billed by tokens continue to use per_1m_tokens.

We recommend keeping the default unit as per_1m_tokens and overriding price_unit only on per-second models. If your whole site bills per second, you can set data.price_unit to per_second.

Optional request signing

Many sites can expose GET /api/provider/pricing publicly.

If you are concerned about long-term scraping of your pricing API by third parties, you can enable hvoy's optional signature verification. This feature is optional:

• When disabled, the API stays a public GET
• When enabled, only signed hvoy collection requests are accepted
• If your prices can be public, you do not need these headers

Request headers

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

Signature algorithm

The site and hvoy agree on an auth_secret offline. Before going live, contact us to have one assigned.

Signing rule:

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

Where:

• ts is a Unix timestamp in seconds
• A signature is valid for 1 minute

Server-side verification

When the site receives a request:

1. Read X-Hvoy-Ts
2. Read X-Hvoy-Sign
3. Check that ts is within 60 seconds of the current server time
4. Recompute hex(HMAC-SHA256(auth_secret, ts)) with the locally stored auth_secret
5. Compare the results and allow the request only if they match

Default secret for test collection

The "fetch test" tool on the hvoy documentation page adds the signature headers automatically and uses this fixed test secret:

hvoy_provider_pricing_test_secret_v1_20260522

We recommend temporarily accepting this test secret during integration, then switching to your own production auth_secret once onboarding is complete.

Claude compatibility

Reference: Claude's official pricing documentation:

• Claude pricing

Map the fields as follows:

• cache_input_price equals Claude's cache hits and refreshes.
• cache_create_price is the general "cache write price" field. For Claude it always maps to 5-minute cache writes.
• cache_create_price_1h adds Claude's 1-hour cache writes.

For non-Claude sites, or sites with a single cache write price:

• If you have only one cache write price, fill in cache_create_price
• Set cache_create_price_1h to null
• If caching is not supported at all, set all 3 cache fields to null

Standard response structure

Mixed billing example

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

Notes:

• data.price_unit is the default; in this example the default is per_1m_tokens
• The first model has no price_unit of its own, so it is parsed as per_1m_tokens
• The second model sets price_unit: "per_call", so it is parsed per call and unit_price is read
• The third model sets price_unit: "per_second", so it is parsed per second, reading unit_price (the 480p per-second price), billing_basis, and variants

All per-call billing example

For image, video, speech, and other models billed by number of calls. For example, 0.2 CNY per call:

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

Field reference

Top-level fields

data fields

data.models[] fields

Field details and examples

schema_version

The protocol version this response follows.

Requirements:

• Must be returned
• Legacy token-billing APIs can keep returning "1.0"
• Return "1.1" when adding per-call or per-second billing, or a per-model price_unit

Examples:

• "1.0"
• "1.1"

success

Whether this request returned price data successfully.

Examples:

• true
• false

message

Used to return an error reason or additional notes.

Examples:

• ""
• "service temporarily unavailable"

data.currency

The price currency. The protocol currently recommends always using CNY.

Examples:

• "CNY"

data.price_unit

The default price unit. Each models[] item can override it with its own price_unit.

Examples:

• "per_1m_tokens"
• "per_call"
• "per_second"

data.site_name

Site name, mainly used for display and troubleshooting.

Examples:

• "hvoy"

data.site_domain

Site domain, mainly used to identify the data source.

Examples:

• "www.hvoyai.com"

data.updated_at

The update time of this batch of prices, in ISO 8601 with a time zone, for example "2026-04-19T12:00:00Z".

Requirements:

• Must be returned
• Indicates when this batch of prices was generated or last updated
• The collector uses it to judge whether prices are stale

Examples:

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

data.models[].model_name

Stable model identifier, one of the core matching fields.

Requirements:

• Must be a stable ID, not a display title
• Do not return localized display names, marketing names, or decorated titles with spaces
• Do not rename it frequently once published

Examples:

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

data.models[].group_name

Stable group identifier, one of the core matching fields.

Requirements:

• Must be a stable ID, not a display title
• We recommend using the site's actual channel key
• Do not rename it frequently once published. After a rename, the original group is delisted and must be collected again; it takes about 6 hours to appear on the leaderboard.

Examples:

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

data.models[].input_price

Input price. It must be the final price; the collector should not need to convert it.

Compatibility rules:

• Required when the final price_unit = "per_1m_tokens"
• Not needed when the final price_unit is "per_call" or "per_second"

Examples:

• 7.5
• 1.25

data.models[].price_unit

Price unit for this model/group. Inherits data.price_unit when omitted.

Examples:

• "per_1m_tokens"
• "per_call"
• "per_second"

data.models[].unit_price

Per-call or per-second price. It must be the final price; the collector should not need to convert it.

Compatibility rules:

• Required, and must be greater than 0, when the final price_unit is "per_call" or "per_second"
• Not needed when the final price_unit = "per_1m_tokens"
• For per_call, the unit is CNY / call
• For per_second, the unit is CNY / second; it is the final per-second price of the billing_basis.resolution tier, excluding reference video surcharges

Examples:

• 0.2
• 1

data.models[].billing_basis

The tier that unit_price applies to for per-second billing. It currently has a single field, resolution.

Compatibility rules:

• Required when the final price_unit = "per_second"; the model is ignored if it is missing or malformed
• Write resolution as 480p, 720p, 1080p, and so on; only letters, digits, ., _, and -, up to 40 characters, case-insensitive
• The reference tier is 480p: if you offer 480p you must quote at 480p; without 480p, quote the cheapest tier
• Per-second billing is 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

Examples:

• { "resolution": "480p" }

data.models[].variants

Other resolutions for per-second billing, optional. They are shown in a popover next to the price on the home page and the leaderboard.

Compatibility rules:

• Used only when the final price_unit = "per_second"
• 1 to 8 tiers, no duplicate resolutions (case-insensitive)
• Each tier has resolution (required, same format as billing_basis.resolution), unit_price (required, CNY / second, greater than 0), and ref_video_price (optional, surcharge per reference video, CNY / video, 0 or greater)
• It must include a tier matching billing_basis.resolution with a price equal to the model's unit_price, otherwise the model is ignored
• If 480p is present, billing_basis.resolution must be 480p; without 480p, the model's unit_price must equal the lowest per-second price in it, otherwise the model is ignored
• If variants itself is malformed, only variants is dropped and the model price is kept
• If you have only one tier but charge a reference video surcharge, pass a single variants item

Example:

[
  { "resolution": "480p", "unit_price": 0.55, "ref_video_price": 8.25 },
  { "resolution": "720p", "unit_price": 1.15, "ref_video_price": 17.25 }
]

data.models[].output_price

Output price. If input and output are not priced separately, you can return the same value as input_price. If not provided, return null.

Not needed when the final price_unit is "per_call" or "per_second".

Examples:

• 37.5
• 7.5
• null

data.models[].cache_input_price

Cache read price, not cache write price.

Compatibility rules:

• Not needed when the final price_unit is "per_call" or "per_second"
• If the site charges for cache reads / cache hits, put the read price here
• For Claude, use cache hits and refreshes
• If cache reads are not supported, return null

Examples:

• 0.75
• null

data.models[].cache_create_price

Cache write price.

Compatibility rules:

• Not needed when the final price_unit is "per_call" or "per_second"
• If the site has only one cache write price, put it here
• For Claude, use 5-minute cache writes
• If there is no cache write price, return null

Examples:

• 9.375
• null

data.models[].cache_create_price_1h

1-hour cache write price.

Compatibility rules:

• Not needed when the final price_unit is "per_call" or "per_second"
• Fill in only when the provider has a separate 1h cache write price
• For Claude, use 1-hour cache writes
• Most non-Claude providers can return null

Examples:

• 15
• null

data.models[].enabled

Whether this model + group is currently available for sale.

Semantics:

• true means the combination is currently available
• false means the combination is explicitly unavailable or temporarily offline
• If the field is missing, the collector treats it as true
• If a model + group combination does not appear in the list at all, this API does not provide a price for it. The collector treats it as unmatched and must not infer that it is offline

Recommendations:

• If a combination is known to exist but is currently offline, keep the record and return enabled: false
• Do not express a temporary outage by removing the record

Examples:

• true
• false

data.models[].note

Additional notes, not used in collection logic.

Examples:

• "Promotional price"
• "Sales paused"

Full response example

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

Error response example

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

Notes:

• When success=false, data can be omitted.
• If the site wants to keep returning data for debugging, it may, but the collector must not rely on it.

Collection and matching rules

hvoyai.com matches records during collection as follows:

1. Read the data.models list
2. Match local monitoring configuration by model_name + group_name
3. Determine the record's final billing unit:
   • If models[].price_unit is set, use models[].price_unit
   • Otherwise use data.price_unit
4. Read price fields according to the final billing unit:
   • per_1m_tokens: read input_price, output_price, cache_input_price, cache_create_price, cache_create_price_1h
   • per_call: read unit_price
   • per_second: read unit_price, plus billing_basis and variants
5. Read the record's:
   • enabled

Third-party implementations should therefore ensure that:

• model_name is a stable ID, not a display name
• group_name is a stable ID, not a display name
• model + group combinations are not duplicated. If they are, the collector uses only one of them

Unmatched semantics:

• If a model + group is missing from the API, the collector records it as unmatched
• Unmatched does not mean explicitly offline

Numeric constraints

We recommend the following constraints:

• All price fields should be JSON numbers
• Do not return numeric strings such as "7.5"
• Prices must not be negative
• Use null for missing values, not empty strings
• Keep 2 to 6 decimal places
• In per_call and per_second modes, unit_price must not be 0. For temporarily free or offline items, use enabled: false or omit the combination
• Each variants tier's unit_price must be greater than 0; ref_video_price must be 0 or greater, and omitted when there is no surcharge
• variants has at most 8 tiers

Minimal implementation

If a third party wants to start with a minimal version, the smallest response is:

{
  "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
      }
    ]
  }
}

Minimal per-call version:

{
  "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
      }
    ]
  }
}

With per-second models, provide at least price_unit, unit_price, and billing_basis.resolution:

{
  "schema_version": "1.1",
  "success": true,
  "data": {
    "currency": "CNY",
    "price_unit": "per_1m_tokens",
    "updated_at": "2026-10-13T12:00:00Z",
    "models": [
      {
        "model_name": "doubao-seedance-2.5",
        "group_name": "video",
        "price_unit": "per_second",
        "unit_price": 0.55,
        "billing_basis": { "resolution": "480p" }
      }
    ]
  }
}

Recommended additions later:

• cache_input_price
• cache_create_price
• cache_create_price_1h
• enabled
• note

Collection warning codes

When the pricing API is collected, every model that is skipped or partially ignored produces a warning in this format:

models[<i>] <reason_code>:<model>/<group>

<i> is the item's index in data.models. variants_dropped appends one more segment with the reason, for example models[<i>] variants_dropped:<model>/<group>/too_many.

You can check your API with the fetch test page. The results show these warnings and their explanations.

variants_dropped reasons: