Price Drift Fixtures for OpenAI-Compatible SDK Workbooks (September 2026)

[chawkian]

Pricing note checked during the September 15, 2026 run: the live AIWave pricing endpoint returned success=true, pricing version a42d372ccf0b5dd13ecf71203521f9d2, group_ratio.default=1, and group_ratio.vip=0.9. The dated static snapshot returned checked=2026-09-10, currency=USD, unit=per_1m_text_tokens, and pricing version 8c7a0c0b30661ccbc13d142cb54d1e4ae445fe774b2c6fa501080db97c7a3e56. Always recheck the current endpoint before using these rows in billing math.

Most SDK examples show how to send a request. Fewer examples show how to preserve the rate card that made the request understandable later. That gap becomes painful when a workbook, notebook, or cost forecast ships with model prices that were correct yesterday and ambiguous today.

The useful artifact is not a giant pricing database inside the SDK. It is a small price drift fixture that sits beside examples and tests. The fixture records what the example believed about a model row, where that row came from, when it was checked, and which account or key multiplier was intentionally applied. Then a CI job can compare the fixture with the current pricing surface and decide whether to fail loudly, warn, or regenerate the example output.

For an OpenAI-compatible client, the fixture can stay compact:

{
  "fixture_type": "price_drift_check",
  "sdk_family": "python",
  "base_url": "https://aiwave.live/v1",
  "pricing_source": "https://aiwave.live/api/v1/pricing",
  "live_source": "https://aiwave.live/api/pricing",
  "pricing_checked": "2026-09-15",
  "snapshot_checked": "2026-09-10",
  "group": "default",
  "group_multiplier": 1,
  "models": [
    {
      "id": "deepseek-v4-flash",
      "input_usd_per_1m": 0.638,
      "cache_hit_usd_per_1m": 0.0202884,
      "output_usd_per_1m": 1.914,
      "effective_date": "2026-08-27"
    }
  ]
}

This is deliberately different from a marketing price table. A marketing page can explain the available models. A fixture has a narrower job: make an example reproducible enough that future maintainers can see whether a change came from the SDK, the route table, the billing group, or the underlying price source.

During this run, I checked the live AIWave pricing surface and the dated static snapshot. Selected default-group base rows from the static snapshot were:

Model ID	Input / 1M	Cache-hit input / 1M	Output / 1M	Effective date
deepseek-v3.2	$0.154	n/a	$0.308	2026-08-27
deepseek-v4-flash	$0.638	$0.0202884	$1.914	2026-08-27
deepseek-v4-pro	$1.914	$0.0637362	$5.742	2026-08-27
glm-5.1	$2.10	$0.680001	$6.5999997	2026-08-27
kimi-k3	$4.50	$0.90	$22.50	2026-08-27

If the same example is run with a VIP key, the fixture should not silently overwrite those base rows. It should add group_multiplier=0.9 and calculate an effective estimate separately. That keeps the public rate card, the key billing group, and the forecast output from collapsing into one unexplained number.

The best test is small. Load the current pricing JSON, find each fixture model, compare the pricing version, compare the effective date, and compare each numeric row within a strict tolerance. If the pricing version changes but the rows do not, the example can continue with a note. If a row changes, the example should force regeneration before the workbook is published.

There is one more edge case worth testing: removed or temporarily hidden models. A price drift checker should treat a missing row differently from a changed row. A changed row means the workbook can be regenerated from current public data. A missing row means the example may be teaching a route that is no longer available to ordinary users, so the release should pause until someone confirms whether the model is intentionally hidden, renamed, or still reachable through a controlled account group. That distinction keeps SDK examples from becoming accidental route promises.

For Python examples, I would keep the fixture loader boring on purpose: plain JSON, decimal-safe parsing, deterministic sorting by model ID, and one assertion error per changed field. The output should be useful in a pull request without asking reviewers to run a private account. Something like deepseek-v4-flash output_usd_per_1m changed from 1.914 to X; refresh fixture from https://aiwave.live/api/v1/pricing is enough. The maintainer can then decide whether the example should follow the new public rate card or keep an older historical note.

I like this pattern because it teaches a production habit without requiring private billing logs. The SDK does not need to know a customer's balance, request body, or account history. It only needs to show which dated public price source and which multiplier shaped the example at the moment it was written.

Discussion question: should SDK repositories keep price drift fixtures checked into source control, or generate them during release so examples always reflect the latest public pricing surface?