API Reference

Billing lifecycle

The four stages keep spend bounded and the final amount reproducible.

Rate snapshot

At create time, the selected catalog rate is copied to the session as rate_snapshot_id.

Preauthorization

The configured bounded amount is reserved from the owning prepaid wallet.

Server usage

Accepted inbound and outbound audio duration is measured by the gateway/worker lifecycle.

Settlement

The terminal session settles from server/provider usage and releases any unused reservation.

Usage fields

These fields are normalized across session responses and terminal response.done events.

Field	Type	Description
`model`required	`string`	Catalog model selected for the session.
`provider`required	`string`	Server-side provider label used for support and accounting.
`pricing_source`required	`string` upstream_derived	How the selling rate was sourced.
`rate_snapshot_id`required	`string`	Immutable rate reference captured at session creation.
`audio_in_ms`required	`integer`	Accepted inbound audio duration in milliseconds.
`audio_out_ms`required	`integer`	Emitted outbound audio duration in milliseconds.
`billed_cents`required	`integer`	Final settled amount in the account currency unit.

What can end a session

A short silence does not by itself prove that the server response is complete.

Client calls POST /v1/voice/sessions/{session_id}/end with an optional bounded reason.
The response lifecycle emits response.done with normalized usage.
Idle expiry can settle a session when it is read or when the lifecycle worker reaches its deadline.
Provider or worker failure produces a terminal failed session and a bounded error code.

Environment boundary

Pricing and readiness are runtime values, not proof that every environment can reach a real provider.

The public catalog only exposes models whose management-plane readiness and selling rate are approved. Local/mock acceptance proves contract and billing behavior; provider-test and targeted UAT remain separate authorization and evidence boundaries.