Usage and pricing

The v0.15 tagged snapshot contains 231 signed cards in catalog /3, with modality token dimensions and per-unit image, audio, video, character, and request rates. Missing media rates produce partial billing. Catalog /3 needs v0.11; domain-separated v2 catalog signatures need v0.12. Keep overlays and readers aligned.

opentine records provider, model, and normalized usage as opaque provenance, then estimates cost from a pinned, effective-dated catalog. Provider usage is not a final invoice: credits, taxes, enterprise terms, regional adjustments, and post-processing may differ.

Normalized records

Usage keeps exclusive input, output, cache-read, cache-write, and reasoning dimensions so the same token is not charged twice. BillingResult reports complete, partial, unknown, or unmetered, plus its known subtotal, warnings, calculation inputs, catalog provenance, and selected rate card.

All arithmetic uses Decimal. The legacy numeric cost field remains the known USD subtotal, so it may be nonzero while an incomplete billing.amount_usd is null.

Catalog resolution

1. Explicit adapter or run rates=, when the reported model still matches.
2. An explicitly selected catalog or TINE_PRICING_CATALOG.
3. Workspace .tine/pricing.json.
4. User $XDG_CONFIG_HOME/opentine/pricing.json.
5. The bundled signed snapshot.
6. An explicit unknown result, never another provider's price.

tine pricing list --provider openai
tine pricing show openai gpt-6.1-sol --json
tine pricing check
tine pricing update ./new-signed-catalog.json

# Read-only calculation over a recorded run
tine price result.tine --at 2026-08-22

Inference never downloads prices. Updates are explicit and signed catalogs must verify before installation. Unsigned local overlays can represent negotiated discounts or infrastructure cost without altering the signed upstream snapshot.

Recorded cost versus post-hoc price

tine cost reports the cost stored when the run was captured. tine price recomputes a read-only view from the recorded (provider, model, usage) tuple. --at DATE pins rate-card selection to that date without changing the run. A missing card, provider, or usage record remains explicitly unknown.

Time-of-day schedules

The opentine-pricing/2 schema adds ordered UTC peak/off-peak windows with all, weekday, or weekend scope. The first matching window replaces only the rate dimensions it names. A card without a schedule behaves exactly as it did under opentine-pricing/1, and /1 catalogs and overlays remain loadable.

A date passed to tine price --at selects the card for the whole run; each step's recorded timestamp still selects its schedule window. Without --at, each step uses its recorded day and time, falling back to today when no timestamp exists.

Coverage is not an allowlist

The signed snapshot bundled with v0.18.2 covers text, image, audio, video, and regional cloud namespaces. Execution support and catalog coverage remain separate; missing exact cards stay unknown, and a used media dimension without its own rate makes billing partial.

Expanded catalog coverage

Catalog /3 adds Gemini Omni Flash, image/TTS/Live/Lyria models, OpenAI realtime/audio/image/transcription families, and MiniMax M3.1 Flash. Effective dates and service tiers determine which card applies. Per-unit rates and explicit same_rate_as relationships keep media from being silently priced as text.

• claude-fable-5-1 carries its source-confirmed cache-read exception and no fast-mode modifier.
• gpt-6-astra includes its whole-request long-context threshold plus batch, flex, and fast modifiers.
• qwen3.8-27b and the hosted qwen3.8-flash carry implicit and explicit cache tiers.
• deepseek-v4-flash-vision-exp is date-scoped across the provider's 2026-08-23 weekend-rule change.

qwen3.8-flash-next remains distinct from the hosted qwen3.8-flash. Missing exact cards stay unknown. Workspace overlays require uppercase ISO currency codes such as USD. Unsigned workspace overlays produce a stderr notice; OPENTINE_TRUST_WORKSPACE_PRICING=1 suppresses it.

Streaming and strict budgets

Post-hoc pricing now includes billed done, think, and error steps and recorded fast, priority, flex, and geographic tiers. Older runs may re-price higher without changing their recorded totals. Gemini 3.5 Flash calls after its October 7 retirement re-price unknown.

Imported costs move to opentine.source_reported_cost and are never summed; source billing blocks are dropped. Price imported usage with --price or later with tine price. A local-provider label alone cannot make an imported call unmetered.

Signed workspace catalogs older than the bundled or installed snapshot are ignored with a notice. A different signed catalog at the same generation timestamp is refused. Unsigned operator overlays remain explicit overrides.

Some OpenAI-compatible services do not return stream usage unless include_usage=True, while others reject that field. opentine uses a provider allowlist and adapter overrides rather than sending it everywhere. Confirm billing.status on a short streamed call before trusting cost enforcement.

1from opentine import Budget
2
3budget = Budget(
4    max_cost=1.00,
5    max_steps=25,
6    strict_cost=True,
7    on_breach="stop",
8)

strict_cost=True stops before the next model call after a hosted price or observed usage dimension becomes indeterminate. Local adapters default to unmetered, not “free”; add explicit rates to account for infrastructure.

Read the tagged pricing reference for exact rate-card and overlay rules.