Skip to main content
The doctrine in one line: unknown stays unknown. A cost Nika cannot prove is never rendered as $0.00, a local model is unpriced — your compute, your electricity — never « free », and an estimate always says which side of the truth it sits on: a floor (≥) or a ceiling (≤).

The vocabulary

Every cost surface speaks the same four words: A task goes UNBOUNDED in one of three ways, and its row names which one:
  • UNBOUNDED — no max_tokens declared · the task has no output limit. You can fix this one: declare max_tokens: and, on a priced model, the report becomes a hard ceiling (the check prints that exact hint).
  • UNBOUNDED — no catalog price (local model; spend not metered) · the task is bounded but the model has no price row. Local models stay here by design — pricing your own hardware would be invention. A cloud model missing from the catalog reads (cloud provider; spend unpriced) instead.
  • UNBOUNDED — for_each over an expression (unknown count) · a fan-out whose item count is known only at run time.

Before a token: the COST rung

nika check audits cost statically, next to the plan and the permits — the same ladder, every time. On weekly-update.nika, a cloud workflow whose one task declares no max_tokens, the COST rung and its hint read:
Declare max_tokens: 4096 on that task and the same rung reads:
The ceiling is $15 per million output tokens × 4096, at the catalog price of the snapshot the rung names; the prompt’s input tokens, exec: and MCP calls are outside it. nika explain <file> narrates the same numbers in beginner words — ≤ $0.0614 worst case · ≥ $0.0614 cheapest path, and for a local model local models: your compute · tokens unpriced — not « free » — and nika run --dry-run carries them onto the plan.

The budget gate: refusal, not remorse

Priced before the first token, refused before the run. nika check finds no max_tokens on the update task and marks it UNBOUNDED. One line, max_tokens: 4096, gives it a worst-case output ceiling of $0.0614: $15 per million output tokens × 4096. With --max-cost-usd 0.05, nika run refuses to start (NIKA-1709, exit 2): no model is called and no run is recorded. Every terminal line and number is captured from the real CLI on nika 0.121.0, offline and with no API key. Prices are catalog estimates; the receipt, the meter and the stamp are illustration.

--max-cost-usd is a block-before-spend gate, not a post-hoc alarm:
  • If the static floor already exceeds the budget, the run refuses to start (exit 2, before any provider is touched):
  • The pre-start refusal prices the effective model — --model override included.
  • If unbounded work rides along, the gate says so loudly on stderr — a budget over work with no ceiling is a promise it names, not one it fakes.
  • Mid-run, the ledger stops the workflow the moment metered spend crosses the budget (NIKA-1704) — settled tasks stay settled, the trace records what was spent.
  • The flag itself is guarded: a non-finite value (NaN, inf) is rejected at parse time — a budget that cannot compare is not a budget.

Repeated runs on an unpriced API route

A server operator can authorize bounded runs without a fresh cost review each time, using nika serve --cost-policy. The rule names an exact unpriced API route and limits requests, output, request time and runs per window. Unknown prices remain unknown. With operator-declared prices, the declared worst case must fit every binding ceiling; without them, every USD ceiling must be absent. Read Standing cost rules for startup syntax, supported routes, admission evidence and recovery. An image or speech builtin bills its provider the way a model call does, so the same doctrine holds: a media call is priced from a dated table, or it is unpriced, never $0.00.

The media price table

The engine carries a price table for paid media, kept apart from the model catalog. Each row names a provider, a model, a unit, a rate in US dollars and the provider’s public price page, read on the date the row carries. Every row in 0.124 is dated 2026-10-27 (standard tier, paid usage): Each Gemini model also has the per-token rates of the same page, which bill the usage a response reports (per 1M tokens, input / image output / text and thinking output): gemini-3.1-flash-image 0.50 / 60 / 3, gemini-3-pro-image 2 / 120 / 12, gemini-2.5-flash-image 0.30 / 30 / 2.50, gemini-3.1-flash-lite-image 0.25 / 30 / 1.50 and gemini-nano-banana-2.1 1.50 / 30 / 7.50. The ElevenLabs families follow its models page. xAI images keep the $0.02 floor per image they already had in 0.123.2, and their bill is the exact spend xAI reports. A request is priced the way its provider bills it. A Gemini size class is provider_options.image_size, else the class of an exact size: by its longer edge, else 1K. The floor of quality: auto is the cheapest price listed for its size, and the floor of an unlisted size the cheapest at its quality. An image whose response reports no usage is billed at the dearest row the request leaves open: quality: auto with no size: bills $0.211 on gpt-image-2, never $0.005. Name the size and quality you mean.

What a capped run does

Under a cap (--max-cost-usd, a project ceiling:, or a beat’s plafond:, which every beat has):
  • At launch, a priced call with literal arguments adds its floor to the run’s cost floor: its price per image times n:, or its rate per character times its text. A paid call the table cannot price is refused with NIKA-1709 before the run starts, and no request is sent: OpenAI’s default voice gpt-4o-mini-tts (OpenAI prices it per token, and its speech response reports no usage), gpt-image-1.5 and gpt-image-1-mini (which OpenAI shuts down on 2026-12-01), and any model id the table does not list, in the workflow itself or in a child or grandchild workflow it calls.
  • Billed from usage only. gpt-image-2.5-sunburst and gpt-image-2.5-flare publish no price per image, and speech whose text only the run renders has no length before the run. nika check marks both METERED: they run under a cap, and only a zero cap refuses them at launch.
  • Before every request, the rendered call is judged against what the cap leaves, less the floors of the paid media calls still in flight. A provider, model, quality:, size:, n: or text: that only the run decides is judged here: the call is refused with NIKA-1704, never retried, when the table cannot price it or its floor exceeds what is left. An admitted call holds its floor until it returns, so the items of a capped for_each, parallel or not, cannot launch past the cap together.
  • An agent: judges each media call its tools make the same way, against what its task’s remainder leaves after the loop’s own model turns and the floors of its concurrent calls. A refused call goes back to the model, and nothing is sent.
Every call is billed, on its output and in its manifest: cost_usd, with cost_basis saying how (catalog_rate_x_usage: the token rates times the usage the provider reported; catalog_price_x_images: the price per image, when no response reports usage; catalog_rate_x_characters: the rate per character times the characters sent; provider_reported: xAI’s own figure) and cost_as_of, the date of the rates. Each response of a Gemini n: batch is billed on its own. A call that fails after its provider billed keeps that spend: a batch whose later request fails keeps the bill of the images already rendered, and a render that fails after its answer keeps its bill. The run ledger debits it as it debits a model’s, per attempt: a capped run stops mid-run (NIKA-1704) once media spend crosses the cap, and a retry is judged against what is left. The run’s prologue records the table (media_pricing), and the cost replay of nika trace verify refuses a journal that recorded other rates. Without a cap, an unpriced paid call runs and is counted in spend.unpriced_calls: the total reads unpriced, or partially_priced beside priced spend, and a child workflow’s unpriced calls reach its parent’s total. A capped run counts some calls unpriced too: a request that broke after it left (the provider may have billed it), a call dropped in flight (a fail_fast sibling, a timeout:, a Stop; its floor stays consumed) and a GPT Image 2.5 response that reports no usage. Once a paid call has billed without a figure, the capped run refuses any later call billed only from its usage. local and mock media, and the keyless provider: system voice, bill no provider. The system voice runs under any cap and reports its cost as unpriced local work (cost_unpriced: local_model), like a local model. nika:image_fx, nika:chart and nika:image_compose are local pixel work, not paid media.

On the COST rung

nika check gives each paid media call a row: its floor, the rate and unit that set it and the table’s date, or METERED, UNPRICED, or DECIDED AT RUN when a template or an agent’s tools choose the provider or the model. A composed child’s calls get rows too. A workflow that renders a cover with gpt-image-2 at quality: low and a poster with gpt-image-2.5-flare, then speaks one line with tts-1 and the same line with OpenAI’s default voice, reads:
A from figure is the least the call can cost. Under any cap, the same workflow is refused before the run starts, and the refusal names every model the table prices:
Both captured offline from nika 0.124.0, with no provider key. nika check --json lists the same rows under cost.media, and the refusals a cap would raise under failure_plan: unpriced_media_cap for a call the table cannot price, priced_image_over_cap and priced_speech_over_cap for a priced floor that a smaller cap refuses, each with its task and a message naming the call. A beat always runs under its plafond:, and a project ceiling: caps a plain nika run that passes no --max-cost-usd, so both refuse unpriced paid media: nika arm shows such a beat UNREADY with NIKA-1709 (Arming a project). A beat cannot drop its cap. Switch the call instead: model: tts-1 or tts-1-hd, a priced ElevenLabs model or the system voice for speech, gpt-image-2 or a GPT Image 2.5 model for images, or local / mock.

After the run: the totals stay honest

Every run ends with a totals line that never turns an unknown price into $0.00. nika run hello.nika on the introduction’s mock/echo workflow ends:
Its one call is unpriced, so the total is a word, not a number. A run that calls no model, no paid media and no keyless voice says unmetered. When priced and unpriced calls share a run, the total reads ≥ $… (N unpriced): the ≥ is printed because an unpriced call rode the run. Per-task spend rides the trace itself (cost_usd on the terminal events), so nika trace show and the run report read the recorded ledger — never a summary’s opinion.

Where prices come from — and when they rot

Prices are a catalog fact with provenance, not a constant: nika check --json carries the pricing snapshot (source · date · hash · derived counts) so a cost claim is traceable to the table that produced it, and nika doctor warns when the snapshot is stale enough to distrust — an old price table silently undercounts, which is the one direction honesty cannot tolerate. Cache-aware accounting follows the OpenTelemetry GenAI convention (input includes cache reads), so exported traces mean the same thing your dashboards expect.

The workflow-side controls

  • max_tokens: per task · turns UNBOUNDED into a ceiling on a priced model (a local model stays unpriced).
  • agent: budgets (max_turns · token budgets) bound the loop the same way — exhaustion is a named failure, never a silent overrun.
  • nika check before nika run, always: the cost story is part of the same pre-flight as permits and secrets.
Local inference corollary: a workflow that runs entirely on ollama/…, llamacpp/… or vllm/… reports unpriced (N calls), not a dollar total — Nika never converts « I don’t know the price » into « it’s free ». That distinction is the whole doctrine.