Serve a pricing endpoint

If you work at a model or inference provider, this is the highest-value thing you can do for the developers costing out your API. Right now your prices reach this catalog because a person reads your pricing page. That is slow, it breaks whenever you restyle the page, and when it breaks the wrong number gets published under your name. Publish one endpoint instead and that stops happening. We poll it every day, so the day a rate moves we know, and the catalog is corrected from your own numbers rather than from a guess at your page.

This is not a new standard. OpenRouter and LiteLLM already publish per-token rates in this shape, and this project already pulls from both. The only addition is the two meters that voice needs: characters of text and seconds of audio.

What we need

A single HTTPS GET that returns your current rates as JSON.

GET https://api.acme.com/.well-known/pricing.json

{
  "provider": "acme",
  "updated": "2026-08-01",
  "currency": "USD",
  "models": [
    {
      "id": "acme-tts-1",
      "name": "Acme TTS v1",
      "modality": "tts",
      "rates": [
        { "meter": "text_input", "amount": "0.000030", "unit": "character" }
      ]
    },
    {
      "id": "acme-stt-1",
      "modality": "stt",
      "rates": [
        { "meter": "audio_input", "amount": "0.0043", "unit": "minute" }
      ]
    }
  ]
}

That is a complete, valid response.

The two requirements that make it worth doing

Generate it from whatever your billing system treats as the source of truth. This is the whole point. An endpoint a human edits by hand is a pricing page with extra steps: it will drift, and because we poll it, that drift becomes visible rather than staying quietly wrong. If the number you serve is the number you bill, the endpoint is correct permanently and you never think about it again. Quote every rate per one base unit: one character, one second, one token, one request. Never per thousand or per million. This is where public pricing data goes wrong most often, because $30 is a plausible price per million characters and a catastrophic one per thousand. If the number is small and the unit is singular, there is nothing to misread. Publish amounts as strings for the same reason: 0.0000003 as a JSON number does not survive a round trip through every language’s float parser.

Serving it

Requirement	Why
A stable HTTPS URL that does not move	It goes in a config file. `/.well-known/pricing.json` on your API host is a good convention. Plain HTTP is rejected: a rate that can be rewritten in transit is worse than no rate.
No authentication	So client-side cost calculators can read it too. A registered URL may not embed credentials, since provider files are public.
`Access-Control-Allow-Origin: *`	Same reason.
`ETag` or `Last-Modified`	So daily polling costs you a 304 rather than a payload.
A bare URL, no query string	Nothing to parameterise: rates are public and identical for everyone. Not enforced, but it keeps caching simple.

It does not need to be fast or highly available. We poll once a day and treat a timeout as a transient failure, never as a price change.

Fields

Top level

Field	Required	Notes
`provider`	yes	Short stable id for your company, lowercase.
`models`	yes	The list below.
`currency`	no	Must be `USD`. Defaults to `USD`, and a feed declaring anything else is rejected: this catalog publishes USD only and does not convert.
`updated`	no	ISO date the rates last changed.

Per model

Field	Required	Notes
`id`	yes	The exact string your API accepts. See below.
`rates`	yes	One entry per priced meter.
`name`	no	Human-readable name.
`modality`	no	`stt`, `llm`, `tts`, `s2s`, or `vad`. Inferred from the rates when omitted, except for `vad`, which is indistinguishable from `stt` by price alone.
`status`	no	`ga`, `preview`, or `deprecated`.
`sunset_on`	no	ISO date the model stops accepting traffic.
`docs_url`	no	Link to that model’s docs.

Per rate

Field	Required	Notes
`meter`	yes	What is being counted. See the grid below.
`unit`	yes	The base unit the amount is quoted per.
`amount`	yes	Decimal string, per one unit.
`plan`	no	Your plan name, when the rate is plan-specific.
`from_quantity`	no	Lower bound of a volume tier, in `unit`s per month.
`voice_class`	no	When cloned or premium voices bill differently.
`effective_from`	no	ISO date, for a price change you have already announced.

A rate with no plan, from_quantity, or voice_class is your headline rate. Publish at least one of those per meter, or there is nothing to compare against.

Supported meter and unit pairs

Every combination below maps to exactly one field in this catalog. Anything not listed is rejected rather than guessed at, because a wrong unit and a wrong price look identical once stored.

Meter	Unit	Catalog field	Conversion
`agent_session`	`minute`	`agent_kminutes`	amount x 1,000
`audio_input`	`minute`	`input_audio_kseconds`	amount x 1,000 / 60
`audio_input`	`second`	`input_audio_kseconds`	amount x 1,000
`audio_input`	`token`	`input_audio_mtok`	amount x 1,000,000
`audio_output`	`minute`	`output_audio_kseconds`	amount x 1,000 / 60
`audio_output`	`second`	`output_audio_kseconds`	amount x 1,000
`audio_output`	`token`	`output_audio_mtok`	amount x 1,000,000
`cached_text_input`	`token`	`cache_read_mtok`	amount x 1,000,000
`request`	`request`	`requests_kcount`	amount x 1,000
`text_input`	`character`	`input_kchars`	amount x 1,000
`text_input`	`token`	`input_mtok`	amount x 1,000,000
`text_output`	`token`	`output_mtok`	amount x 1,000,000

Get the model id right

This is the field most often wrong and the only one that makes an endpoint machine-usable. id must be the literal string a caller passes to your API. Not the marketing name, not the docs slug, not the pricing-page row label.

{ "id": "acme-tts-1" }          // correct: this is what the API accepts
{ "id": "Acme TTS v1 (HD)" }    // useless: nothing can route on this

Every downstream tool has a fuzzy matching layer purely because providers publish the second form. Getting this right deletes that layer.

Check it before you ship it

git clone https://github.com/mahimailabs/voice-prices && cd voice-prices
make install
make feed-check FEED=https://api.acme.com/.well-known/pricing.json

This validates the response, converts every rate, and diffs it against what this catalog currently publishes about you. It works on a local path too, so you can check what your build produces before it goes live:

make feed-check FEED=./pricing.json

It exits non-zero when something drifts or cannot be mapped, so it doubles as a check in your CI: fail your build the day your published rates stop matching what you actually charge. Call the module directly there to avoid make’s own error line, which signals findings rather than a crash:

FEED=./pricing.json uv run -m prices feed_check

Register it

Open an issue with the URL, or send a pull request adding one line to your provider file:

pricing_feed_url: https://api.acme.com/.well-known/pricing.json

From then on a scheduled job polls your endpoint daily and flags any rate that has moved away from the catalog.

Polling never rewrites a price on its own. A moved rate alerts a maintainer, who confirms it and updates the entry by hand. No job in this project is allowed to mark a price as verified, which is what makes the dates on every page mean something. How Fresh? explains the rule.

Anything that does not fit the shape above, open an issue and we will work it out.

​What we need

​The two requirements that make it worth doing

​Serving it

​Fields

​Top level

​Per model

​Per rate

​Supported meter and unit pairs

​Get the model id right

​Check it before you ship it

​Register it

What we need

The two requirements that make it worth doing

Serving it

Fields

Top level

Per model

Per rate

Supported meter and unit pairs

Get the model id right

Check it before you ship it

Register it