Budget Variance Ledgers for OpenAI-Compatible SDKs (September 2026)

[chawkian]

Pricing note checked during the September 19, 2026 run: the public AIWave pricing snapshot returned 56 model rows, currency USD, unit per_1m_text_tokens, checked=2026-09-10, updated_at=2026-09-18, and pricing version 83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5. The live route table returned success=true, 68 route rows, pricing version a42d372ccf0b5dd13ecf71203521f9d2, and group ratios default=1 and vip=0.9. Recheck both endpoints before using these values for billing decisions.

One thing I would like more SDK examples to show is the difference between a cost estimate and a cost investigation.

An estimate is useful before a feature ships. It answers: if this example sends 2,000 requests, uses this model, and generates this many output tokens, what should the spend look like?

An investigation starts after real traffic runs. It answers a harder question: when the actual bill differs from the expected bill, what changed?

For OpenAI-compatible SDKs, that second question gets messy quickly. The code path may still say chat.completions.create. The base URL may still be stable. But the workload can drift in several places: the model alias resolves differently, output length grows, retries multiply, cache hits do not materialize, or a key-level billing group changes the effective multiplier. If an SDK example only includes the request code, maintainers have to reconstruct the economic trail later.

My current preferred artifact is a budget variance ledger committed beside the cost-sensitive example. It is not a private invoice and it should not contain prompts, completions, API keys, user IDs, or account balances. It is a small, dated fixture that compares what the release expected with what sanitized receipts later showed.

A minimal row might look like this:

{
  "fixture_type": "budget_variance_ledger",
  "sdk_family": "python",
  "client_shape": "openai_chat_completions",
  "model_id": "deepseek-flash",
  "pricing_snapshot_version": "83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5",
  "route_table_version": "a42d372ccf0b5dd13ecf71203521f9d2",
  "group_ratio": { "default": 1, "vip": 0.9 },
  "expected": {
    "input_tokens": 180000000,
    "output_tokens": 22000000,
    "usd": 172.2
  },
  "actual": {
    "input_tokens": 194000000,
    "output_tokens": 31500000,
    "retry_requests": 73,
    "usd": 201.95
  },
  "variance_reasons": [
    "output_tokens_exceeded_plan",
    "retry_requests_present"
  ],
  "redactions_required": ["api_key", "prompt", "completion", "user_id"]
}

The exact schema matters less than the boundaries. The ledger should make the expected route, pricing version, token mix, multiplier, and receipt fields reviewable. It should also make unsafe fields impossible to commit. A CI check can reject any row containing key-like strings, raw message content, or identifiers that belong in a private billing system.

Selected public rows from the source I checked:

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-v3.2	$0.154	unknown	$0.308	2026-08-27
glm-5.1	$2.10	$0.680001	$6.5999997	2026-08-27
MiniMax-M2.7	$0.45304	$0.090608	$1.81216	2026-08-27

I think this is especially useful for SDK maintainers because examples often outlive the pricing page they were written against. Six weeks later, someone can run a fixture check and get a precise failure: source version changed, model row disappeared, output grew, retries appeared, or the applied group multiplier no longer matches the release assumption.

It also keeps the public conversation honest. Instead of claiming that one model or route is always the right economic choice, the SDK can show how to audit a dated assumption.

Discussion question: should SDK repositories keep these variance ledgers as static JSON fixtures, or should they generate them during release from the latest public pricing surface and sanitized test receipts?