Expose Route Cost Explanations in AI SDK Responses (August 2026)

[chawkian]

One pattern I would like to see more often in AI SDKs is a first-class cost explanation attached to each routed request. Not just a monthly dashboard, and not only a provider invoice after the fact. I mean a small response-side object that tells the application why this model was selected, what pricing snapshot was used, and which cost assumptions were applied before the request went out.

This matters more as OpenAI-compatible gateways become the normal way to access Chinese models. The client call can look stable while the underlying catalog is changing: model IDs, endpoint support, cache behavior, context limits, and output ratios can all move independently. If the SDK only returns model, usage, and latency, teams still have to reconstruct the decision path later.

I rechecked AIWave's live pricing feed on August 14, 2026 (https://aiwave.live/api/pricing). Current OpenAI-compatible rows included:

Model	Input / 1M	Cached input / 1M	Output / 1M
qwen3-coder-480b-a35b-instruct	$0.0600	n/a	$0.1800
deepseek-v4-flash	$0.1030	$0.0206	$0.2060
qwen3-235b-a22b-instruct-2507	about $0.171233	about $0.0171233	about $1.71233
deepseek-v4-pro	$0.54375	$0.271875	$1.0875
kimi-k2.6	$0.5450	about $0.09343	about $2.2999
glm-5.1	$1.0500	about $0.3400	about $3.3000
ernie-5.0	about $1.232877	about $0.123288	about $4.65756
minimax-m2.5	$0.2500	n/a	$1.0000

Those numbers are useful, but they are only half of what a production application needs. The other half is the explanation of how the SDK used them.

For example, a routed response could include something like this:

{
  "model": "deepseek-v4-flash",
  "usage": {
    "input_tokens": 18400,
    "output_tokens": 920
  },
  "route_explanation": {
    "catalog_snapshot": "2026-08-14T14:00:00Z",
    "required_endpoint": "openai",
    "selected_reason": "fits latency target and cache-miss budget",
    "price_source": "aiwave.live/api/pricing",
    "input_usd_per_1m": 0.103,
    "cached_input_usd_per_1m": 0.0206,
    "output_usd_per_1m": 0.206,
    "cache_assumption": "miss",
    "fallbacks_considered": [
      "qwen3-coder-480b-a35b-instruct",
      "deepseek-v4-pro"
    ]
  }
}

The goal is not to turn every API response into an accounting document. The goal is to make routing behavior explainable at the same grain where engineering teams debug prompts, retries, and latency. When a coding agent suddenly changes model, a finance alert fires, or a customer asks why a workflow slowed down, the route explanation gives the team a dated fact trail.

I would separate this from billing reconciliation. Billing systems need complete ledgers, currency handling, invoices, and account-level controls. SDK route explanations can stay smaller: selected model, pricing snapshot, endpoint type, cache assumption, estimated cost before dispatch, actual usage after completion, and fallback candidates.

This also helps with developer trust. "Unified API for Chinese AI Models" should not mean that model choice becomes invisible. A unified API is strongest when it hides integration friction but still exposes the operational facts that matter for production ownership.

There are a few open design questions:

1. Should route explanations be returned by default, or only when a debug flag is enabled?
2. Should the SDK expose pre-dispatch estimates even when the request later fails?
3. How much fallback detail is useful before the response becomes too noisy?
4. Should applications be able to persist the exact catalog snapshot for audit and replay?

How are you handling this in your own AI SDKs? Do you prefer route explanations in the response payload, structured logs, tracing spans, or a separate cost ledger?