Pricing Contract Canary Fixtures for OpenAI-Compatible SDK Releases (September 2026)

[chawkian]

Pricing drift rarely looks like a broken API call. The client still sends a valid OpenAI-compatible request, the gateway still returns a response, and the example in the docs still appears runnable. The problem shows up later, when a calculator, release note, procurement packet, or customer-facing ledger relied on a price row that no longer matches the route table.

I think SDKs should treat pricing evidence as a small contract fixture, not as prose copied into documentation.

Before posting this, I rechecked the public pricing sources on September 10, 2026. AIWave's live /api/pricing endpoint returned success=true, 64 route records, pricing version a42d372ccf0b5dd13ecf71203521f9d2, group_ratio values of default=3 and vip=1, and OpenAI endpoint metadata for /v1/chat/completions. The dated /api/v1/pricing snapshot returned HTTP 200 with checked=2026-09-10, updated_at=2026-09-10, currency USD, unit per_1m_text_tokens, pricing version 8c7a0c0b30661ccbc13d142cb54d1e4ae445fe774b2c6fa501080db97c7a3e56, and 64 model rows. I also rechecked the official DeepSeek pricing page, Z.AI pricing page, and Alibaba Cloud Model Studio documentation during this run.

Selected public snapshot rows:

Model ID	Input / 1M	Cache-hit input / 1M	Output / 1M	Effective date
deepseek-flash	$0.70	$0.0233	$2.10	2026-09-10
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
qwen3-max	$1.5621977891	null	$6.2487911565	2026-08-27

These are public base rows, not final invoices. A completed request still needs the resolved model, applied account group, cache behavior, output length, retries, and private receipt. The SDK fixture should make that boundary explicit.

Here is the fixture shape I would want in an SDK release:

{
  "fixture_type": "pricing_contract_canary",
  "checked_at": "2026-09-10",
  "live_source": "https://aiwave.live/api/pricing",
  "snapshot_source": "https://aiwave.live/api/v1/pricing",
  "model_id": "deepseek-flash",
  "currency": "USD",
  "unit": "per_1m_text_tokens",
  "required_fields": [
    "input_usd_per_1m_tokens",
    "output_usd_per_1m_tokens",
    "effective_date"
  ],
  "nullable_fields": [
    "cache_hit_usd_per_1m_tokens"
  ],
  "private_receipt_fields": [
    "applied_group",
    "resolved_route",
    "request_id"
  ]
}

The canary should have three outcomes:

Verdict	Meaning	SDK action
pass	Required row exists, units are explicit, and the expected fields are present	Allow examples and route policy to proceed
review	Row exists, but versions, effective dates, nullable cache fields, or provider notes changed	Attach the canary output to the release and require owner review
fail	Source is unreachable, row is missing, or required units are absent	Block the pricing-sensitive release path

The useful part is not the exact JSON. The useful part is that a pricing-sensitive SDK example can prove which row it depended on, when it was checked, and which fields were intentionally excluded from public evidence.

I would keep the canary intentionally narrow. It should stay out of private operating data, message content, reusable access material, payment details, and private contact data. It should only verify public evidence: source URL, checked date, unit, currency, model ID, base rate fields, and cache-field state.

This also helps when a provider changes route semantics without immediately breaking compatibility. A model alias may continue to work while its billing behavior, replacement target, cache policy, or effective date changes. If the SDK has a canary fixture, maintainers can review that difference before updating examples, calculators, or procurement notes.

Discussion question: should pricing contract canaries live in SDK test fixtures, gateway-generated evidence bundles, or both? My bias is both. The gateway owns the freshest route table, but the SDK owns the examples developers copy into real applications.