Usage, settings, and troubleshooting

Voice operations depend on provider configuration, routing decisions, validation, and the quality of submitted text or audio. The verified speech path records usage best effort and returns an estimated cost, but those values are not invoices and the current limits are not approved as permanent entitlements. Use this page to interpret settings, distinguish setup failures from provider failures, and diagnose mock, hosted, and local routing outcomes.

Usage

Interpret usage metadata at the request level. Input size, output duration, provider, model, route reason, and fallback state explain how one generation was processed when those fields are present. estimatedCost is operational metadata and can change with the route or provider; it is not an invoice, account balance, or settlement record.

Best-effort logging means the returned speech response remains the primary evidence that the request completed. A missing usage row should be investigated as a logging or persistence question, not automatically classified as a failed generation. Likewise, a displayed row does not establish a fixed retention period or immutable billing ledger.

The speech handler can record generation usage after processing, but logging is best effort. A generated audio response may exist even when no durable usage row is available. Conversely, a visible usage entry should not be treated as an immutable billing record.

Useful speech metadata includes the provider, model, voice, format, duration, estimated cost, fallback state, route reason, and creation time. These fields help explain one request. They do not establish a fixed plan allowance, invoice amount, or retention period.

estimatedCost is a placeholder estimate. Do not reconcile it as a charge or promise that its calculation will remain unchanged. Usage surfaces can support operational awareness while pricing and billing behavior remain under product review.

When comparing requests, keep route changes in view. Two clips with similar text can use different providers or fallback paths. Provider attribution is needed before latency, quality, or cost estimates are interpreted.

Speech generation can produce best-effort usage metadata without creating an invoice-grade ledger. The speech route can log generation usage on a best-effort basis after processing. estimatedCost is a placeholder estimate and should not be reconciled as a billing charge. Provider catalog state does not establish that credentials are configured or that a provider is healthy at request time.

The speech route can log generation usage on a best-effort basis after processing; start with the returned error code or message rather than changing multiple settings at once. Hosted providers can return setup-required errors when server-side keys are missing; inspect routeReason and fallbackUsed when output quality or provider identity differs from expectation. Do not treat displayed provider state, estimated cost, or current handler limits as guaranteed production status.

Provider settings

After a configuration change, use one short request to verify routing. Compare the requested mode with the returned provider, model, fallbackUsed, and routeReason. This confirms whether the server used the intended adapter or selected a fallback. Do not infer provider health from a static catalog entry or from a successful request made at an earlier time.

Provider catalog entries and provider configuration are separate. The constants file can list mock, OpenAI, ElevenLabs, Cartesia, and local options while the server still lacks credentials for a hosted adapter. A provider marked setup-required will not become available through repeated requests.

Use /voice/settings to review the current configuration surface. Provider keys remain server-side and should not be included in client request bodies. The operations surface does not define every settings control, key-storage guarantee, rotation workflow, or provider-health check, so document only what the inspected interface exposes.

Routing modes express preference: balanced, best quality, fastest, lowest cost, private, fallback, and manual. They do not guarantee the selected provider. Automatic routing can use mock fallback, while private routing fails when no local speech runtime is installed.

After changing provider setup, make one short test and inspect provider, fallbackUsed, and routeReason. A playable result is not enough to prove that the intended hosted route was used.

A provider card and a configured server-side credential represent different readiness conditions. Hosted providers can return setup-required errors when server-side keys are missing. Automatic routing may fall back to mock, while private routing can report unavailable without a local runtime. Text length, audio format, and speed validation can fail before any provider call occurs.

Provider catalog state does not establish that credentials are configured or that a provider is healthy at request time; check provider configuration, routing mode, requested model, voice, format, and speed in that order. Text length, audio format, and speed validation can fail before any provider call occurs; retry only after correcting validation or setup issues; repeated retries do not configure a provider. When a session or usage entry is missing, remember that logging is best effort and persistence remains under review.

Limits

The verified speech handler currently requires text, limits text to 5,000 characters, accepts mp3, wav, or opus, and permits speed values from 0.1 through 10. It also applies shared rate and beta-usage controls.

Those values describe the inspected implementation, not permanent public pricing or entitlement. Do not publish them as a plan guarantee or infer equivalent limits for transcription, dubbing, realtime agents, or phone sessions.

Fixed limits for session duration, concurrency, file size, audio duration, provider quotas, and retention are not documented. When the current UI shows a limit, record the exact surface and implementation version before using it as documentation input.

A limit failure should be corrected at the request or setup stage. Repeated retries do not increase an allowance and can obscure the original error.

Current validation and beta controls describe implementation behavior, not a permanent entitlement. Current rate-limit and beta usage checks exist in the handler but are not approved as fixed public plans or quotas. Audio quality can vary with voice, model, speed, source material, provider, and fallback path. Inspect routeReason and fallbackUsed when output quality or provider identity differs from expectation.

Automatic routing may fall back to mock, while private routing can report unavailable without a local runtime; inspect routeReason and fallbackUsed when output quality or provider identity differs from expectation. Audio quality can vary with voice, model, speed, source material, provider, and fallback path; for local routing, verify that a speech runtime is installed and detected before selecting private mode.

Session failures

Session-related problems can originate in browser permission, media devices, provider setup, connection state, routing, or persistence. Identify which stage failed before changing the agent configuration.

For browser tests, check microphone permission and audio output first. Then verify provider readiness and routing mode. If the connection opens but no response plays, separate input capture, model response, and playback. If a record is missing after an otherwise successful interaction, remember that session persistence and event contracts require review.

Phone-oriented failures should not be handled as browser failures. The phone route is setup and architecture focused, and no live telephony contract was verified. A missing number, callback, transfer, or recording control can be an unavailable capability rather than an operational outage.

Use safe identifiers when reporting a failure. Avoid copying full transcripts, audio, credentials, or personal phone data into routine logs.

Session-related failures may originate in configuration, routing, browser capability, provider readiness, or unverified persistence. Retry only after correcting validation or setup issues; repeated retries do not configure a provider. For local routing, verify that a speech runtime is installed and detected before selecting private mode. Start with the returned error code or message rather than changing multiple settings at once.

Current rate-limit and beta usage checks exist in the handler but are not approved as fixed public plans or quotas; retry only after correcting validation or setup issues; repeated retries do not configure a provider. estimatedCost is a placeholder estimate and should not be reconciled as a billing charge; start with the returned error code or message rather than changing multiple settings at once.

Audio quality

Audio quality can change with voice, model, speed, format, provider, route, and fallback. Begin with a short sample and one change at a time. If quality changes unexpectedly, inspect the returned provider and fallback metadata before adjusting the text.

Mock fallback is especially important. A mock result can validate the interface while sounding different from the requested hosted voice. Label that output accurately and do not use it to judge hosted-provider quality.

For poor pronunciation, simplify the sample and confirm the selected voice and model. For clipped or unplayable output, verify the returned format and decoding path. The API returns base64 audio in JSON; the client must decode it according to format.

Universal guarantees for quality, latency, and language support are not available. Avoid comparing providers through a single unverified test.

Voice, model, speed, format, provider, and fallback choice can all change the perceived result. Check provider configuration, routing mode, requested model, voice, format, and speed in that order.

The speech route can log generation usage on a best-effort basis after processing; for local routing, verify that a speech runtime is installed and detected before selecting private mode. Hosted providers can return setup-required errors when server-side keys are missing; check provider configuration, routing mode, requested model, voice, format, and speed in that order.

Debugging checklist

Change one factor per test. A useful order is validation, provider setup, routing, returned provider, fallback state, format, playback, and only then quality tuning. For local mode, verify that the runtime is installed and detected. For transcription or dubbing, use the dedicated surface and do not apply the speech endpoint contract automatically.

Persistent issues should be reported with the route, current product state, provider, model, voice, routing mode, format, safe result or session identifiers, and exact error. Exclude secrets and unnecessary personal data. Pricing, provider health, limits, and retention remain review items, so troubleshooting should not promise a fixed operational outcome.

A disciplined check of validation, configuration, routing, and returned metadata is more useful than repeated blind retries.

Provider catalog state does not establish that credentials are configured or that a provider is healthy at request time; start with the returned error code or message rather than changing multiple settings at once. Text length, audio format, and speed validation can fail before any provider call occurs; inspect routeReason and fallbackUsed when output quality or provider identity differs from expectation.