Rate-Card Fingerprints for Responses-Compatible SDK Runs (August 2026)

[chawkian]

When an SDK supports an OpenAI-compatible /v1/responses path, I think the acceptance tests should check more than request shape and parsed output. They should also prove that every run can be tied back to the rate card that was current when the request was accepted.

The practical reason is simple: pricing bugs usually do not look like broken JSON. They look like a run that completed, returned plausible text, and only became confusing when somebody tried to explain the bill later. If the SDK only records model name, input tokens, output tokens, and final debit, the team still has to reconstruct which route table, cache rule, and account group were active at that moment.

For the AIWave route I checked today, Aug 31, 2026, the live pricing endpoint returned success=true, 63 rows, group_ratio.default=3, group_ratio.vip=1, and pricing version a42d372ccf0b5dd13ecf71203521f9d2. Using the same published conversion rule as the pricing reconciler, a few VIP x1 base rows resolve to:

Model	Input / 1M	Cache-hit input / 1M	Output / 1M
deepseek-v4-flash	$0.638	$0.0202884	$1.914
glm-5.1	$2.1	$0.680001	$6.6
kimi-k2.7-code-highspeed	$4.725	$0.7125016	$15

Those numbers are not enough by themselves. In a Responses-compatible SDK, I would like the request telemetry to carry a compact fingerprint such as:

{
  "requested_model": "deepseek-v4-flash",
  "served_model": "deepseek-v4-flash",
  "endpoint_family": "responses",
  "pricing_version": "a42d372ccf0b5dd13ecf71203521f9d2",
  "effective_group": "vip",
  "input_tokens": 82000,
  "cache_hit_input_tokens": 64000,
  "output_tokens": 4200
}

The field I care about most is pricing_version. It turns a cost row from a loose estimate into something testable. If a customer exports logs next week, the SDK can still say which rate card it used. If a CI run compares direct provider behavior against the gateway path, it can fail on missing pricing metadata before anyone trusts the ledger. If a model alias moves behind the same OpenAI-compatible interface, the fingerprint makes that movement visible.

My suggested acceptance test is deliberately boring:

1. Call the model catalog or pricing endpoint before the test run.
2. Store the returned pricing version and group ratio.
3. Send one small Responses request through the SDK.
4. Assert that the response metadata includes the same pricing version, the requested model, the served model, token buckets, and the effective billing group.
5. Recompute the estimated row locally and allow only a documented rounding tolerance.

This also creates a useful boundary between SDK behavior and product policy. The SDK does not need to decide whether a default account should use a different multiplier than a VIP account. It only needs to expose the multiplier that was actually applied, together with the source version. Product teams can change policy later without making old logs impossible to audit.

I am curious how other SDK maintainers are handling this. Do you treat pricing metadata as part of the response contract, or only as a dashboard concern? And if you support both Chat Completions and Responses under the same OpenAI-compatible client, do you keep one shared cost schema or separate schemas per endpoint family?