Tool-Fee Ledgers for OpenAI-Compatible SDK Examples (September 2026)

[chawkian]

Pricing note checked during the September 16, 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. Recheck the current endpoint before using these rows in billing math.

SDK examples usually treat add-on work as a footnote. The main request gets a model name, a token estimate, and sometimes a saved response. Tool calls, search steps, media transforms, reranking, or post-processing often disappear into comments like "optional" or "depends on provider." That is exactly where cost surprises enter production.

I would like more OpenAI-compatible SDK examples to include a tool-fee ledger beside the ordinary model request example.

The ledger does not need private account data. It should not include prompts, completions, API keys, user IDs, or customer workload details. It only needs to preserve the budget contract the example was teaching: which base model row was used, which add-on stages were enabled, what each stage was allowed to spend, whether the add-on stage is required or optional, and how the example should behave when the stage would exceed budget.

Current public rows I checked for the base text route:

Model ID	Input / 1M	Output / 1M	Effective date
deepseek-flash	$0.70	$2.10	2026-09-10
deepseek-v4-flash	$0.638	$1.914	2026-08-27
deepseek-v4-pro	$1.914	$5.742	2026-08-27
glm-5.1	$2.10	$6.60	2026-08-27
kimi-k3	$4.50	$22.50	2026-08-27

The add-on side needs a different type of number. A text model row is normally priced per token. A web search step may be priced per operation, a media stage may be priced by duration or unit, and a schema repair step may be another model call with a smaller output budget. Even when the public SDK cannot know every provider-specific charge, it can still teach the right habit: separate the base route estimate from stage budgets, mark which stages are mandatory, and make the failure behavior explicit.

That matters most in examples that look harmless: "answer with citations," "analyze this image," "repair invalid JSON," or "rerank these candidate chunks." Each phrase can hide one or more extra operations. A developer copying the example should see whether those operations are part of the main request contract or optional helpers that can be disabled when the run approaches its budget.

Here is the kind of small Python fixture I mean. It is deliberately runnable without a private account, because it validates the estimate shape before anyone sends a real request:

from decimal import Decimal

BASE_URL = "https://aiwave.live/v1"
API_KEY = "YOUR_API_KEY_HERE"

ledger = {
    "base_url": BASE_URL,
    "model": "deepseek-v4-flash",
    "pricing_source": "https://aiwave.live/api/v1/pricing",
    "pricing_checked": "2026-09-10",
    "group": "default",
    "group_multiplier": Decimal("1"),
    "base_input_usd_per_1m": Decimal("0.638"),
    "base_output_usd_per_1m": Decimal("1.914"),
    "tool_budget_usd": Decimal("0.02"),
    "stages": [
        {"name": "web_search", "required": False, "budget_usd": Decimal("0.010")},
        {"name": "rerank", "required": True, "budget_usd": Decimal("0.006")},
        {"name": "schema_repair", "required": False, "budget_usd": Decimal("0.004")},
    ],
}

def estimate_text_cost(input_tokens: int, output_tokens: int) -> Decimal:
    input_cost = Decimal(input_tokens) * ledger["base_input_usd_per_1m"] / Decimal(1_000_000)
    output_cost = Decimal(output_tokens) * ledger["base_output_usd_per_1m"] / Decimal(1_000_000)
    return (input_cost + output_cost) * ledger["group_multiplier"]

def validate_tool_budget() -> None:
    total = sum(stage["budget_usd"] for stage in ledger["stages"])
    if total > ledger["tool_budget_usd"]:
        raise ValueError(f"tool stages exceed budget: {total} > {ledger['tool_budget_usd']}")

validate_tool_budget()
print(estimate_text_cost(input_tokens=120_000, output_tokens=4_000))

The important design choice is to keep base text cost and tool budget separate. If an SDK folds every add-on into one blended estimate, reviewers cannot tell whether a cost change came from the model row, the billing group multiplier, a tool stage, or a different route policy. If the ledger keeps those fields apart, the example can fail loudly when a required stage exceeds budget and degrade gracefully when an optional stage is too expensive for the current run.

I would also store the add-on ledger with test fixtures, not only in docs prose. A CI assertion can check that every example has a source URL, checked date, group label, required-stage list, and redaction list. That is a small habit, but it turns cost-sensitive examples into something maintainers can review line by line.

Discussion question: should SDK examples expose tool-fee ledgers as first-class fixture files, or keep them inside debug output generated during the example run?