Voice quickstart

This quickstart produces one supported Voice result through the speech-generation path and explains where transcription diverges. The shortest grounded route is to open Voice Studio, choose a configured route, submit text, and inspect the returned audio and routing metadata. A durable session is not required by the verified speech handler, hosted providers can be setup-required, and automatic routing may return mock output when no hosted adapter is ready.

Prerequisites

You need access to the Voice preview and a browser that can open the approved Voice routes. For hosted generation, the selected provider must be configured on the server. Provider credentials are not entered into the speech request and should not be placed in text, model, or voice fields. For private routing, a compatible local speech runtime must be installed and detected; otherwise the route reports that local generation is unavailable.

Prepare a short text sample for the first request. The current handler requires non-empty text and rejects text longer than 5,000 characters. Keep the sample simple so that validation, routing, and playback can be checked independently. Choose one of the implemented output formats—mp3, wav, or opus—and use a speed between 0.1 and 10. Starting near the default speed reduces the number of variables involved in the first test.

Before submitting sensitive material, confirm that the text is appropriate for the chosen provider and intended output. If the workflow involves a real person’s voice or cloning-related configuration, review the consent and safety guidance first. The existence of the Voice surface does not replace permission, privacy, or provider-specific responsibilities.

A first test should also have an explicit success definition: playable audio, the expected format, understandable speech, and metadata that identifies the route. Do not use cost, duration, or usage records as the sole success signal because those fields are estimates or best-effort operational data. Keep the submitted text and returned identifiers available until the provider and fallback state have been reviewed.

A successful first speech request requires a usable Voice surface, valid text, and either a configured provider or an understood mock fallback. The verified speech request accepts text, provider, model, voiceId, routingMode, format, and speed. text is required and is currently limited to 5,000 characters by the inspected handler. Accepted audio formats are mp3, wav, and opus, while speed must fall between 0.1 and 10.

Choose a provider

Open /voice/studio and review the provider or routing controls shown by the inspected interface. Provider catalog entries can be active, setup-required, coming soon, degraded, mock, or local-unavailable. A provider name in the interface does not prove that server-side credentials are present or that the service is healthy at request time.

For the first request, choose one of these paths:

• Select a hosted provider only when its configuration is ready.
• Select balanced or another automatic routing mode when fallback behavior is acceptable and will be reviewed.
• Select manual when the exact provider and model must remain explicit.
• Select private only when a local runtime is installed and detected.
• Use the mock route for interface testing, and label the resulting audio as mock output.

Balanced, best-quality, fastest, lowest-cost, private, fallback, and manual are routing policies rather than guarantees. The actual provider is confirmed by the response metadata. If a hosted provider is unconfigured, changing only the routing mode will not create credentials. Open Voice settings and complete the server-side setup appropriate to the current environment.

If the interface shows a provider as degraded or coming soon, choose another supported path rather than treating the label as a transient error. Lowest-cost and fastest modes are selection preferences, not a promise that every configured provider will be considered or that the displayed route will remain unchanged. Manual mode gives the clearest test when provider attribution is important.

Provider choice determines whether the request uses a hosted adapter, a local runtime, manual selection, or automatic routing. Provider credentials stay on the server; an unconfigured hosted provider produces a setup-required response rather than a successful hosted generation. The response can identify the provider, model, voice, audio format, duration, estimated cost, route reason, and whether fallback occurred. Private routing reports unavailable when no local runtime is installed.

Create a session

The verified speech endpoint does not require a persistent session object. You can submit text and receive audio directly. In Voice Studio, the interface may still present history or session-oriented controls, but those controls should not be made a prerequisite unless the inspected interface explicitly requires them.

For a minimal generation:

1. Enter the prepared text.
2. Confirm the routing mode or provider.
3. Select a voice and model only when those choices are available for the route.
4. Choose mp3, wav, or opus.
5. Leave speed near the default for the first attempt.

The intended result at this stage is a valid request, not a durable conversation. Agent and phone workflows can involve richer session concepts, but their persistence, event ordering, reconnection, and telephony behavior are separate preview concerns. Do not interpret a generated audio clip as evidence that a voice-agent session or phone deployment exists.

If the interface asks for fields not described by the verified speech handler, treat them as surface-specific controls and verify their behavior. Do not copy authentication, streaming, or OpenAI-compatible fields from other Ethen products into the Voice request.

Session-related controls can still be useful for organizing work, but they are outside the minimal API requirement. If a session identifier appears, treat it as interface metadata whose persistence is unverified. Do not build automation that depends on the record surviving reloads, deployments, or retention cleanup until the underlying storage contract is documented.

Basic speech generation can complete without creating a durable session object. The transcription route is visible, but its endpoint contract and output schema were not inspected with the same confidence as speech generation. Submit the request and wait for either audio or a structured setup, validation, routing, or provider error. Review fallbackUsed and routeReason before deciding whether the result came from the intended provider.

Generate or transcribe

Submit the text-to-speech request from Voice Studio. The underlying verified route accepts JSON fields for text, provider, model, voiceId, routingMode, format, and speed. It applies validation, resolves routing, calls a server-side adapter, logs usage on a best-effort basis, and returns safe JSON containing base64 audio and metadata.

A successful result should contain enough information to identify the output and route, including fields such as provider, model, voiceId, format, durationSeconds, estimatedCost, fallbackUsed, routeReason, and createdAt. The UI may turn the base64 audio into a playable result. If it exposes raw metadata, keep it available until the route and fallback state are understood.

Transcription follows a different product surface at /voice/transcribe. The route exists and is described as OpenAI-powered, but its endpoint schema was not directly verified with the same confidence as speech generation. Use the current interface instructions for accepted audio and review the result conservatively. Do not assume diarization, word timestamps, supported-language coverage, batch processing, or exports merely because those concepts appear in hub-level descriptions.

For generated speech, the response is the authoritative place to determine the actual provider path. The requested provider expresses intent; the returned provider and route reason describe what occurred. For transcription, compare the visible result with the source audio; no verified confidence score or review workflow replaces human inspection.

Speech generation has a verified request contract, whereas transcription remains a visible surface with a less complete runtime specification. For transcription, use /voice/transcribe only as a preview surface until its exact API and output contract are verified. Open /voice/studio and confirm that the selected provider or routing mode is not marked setup-required. When mock fallback is used, label the result as mock output rather than presenting it as hosted-provider generation.

Review output

Play the generated audio and compare it with the requested text, voice, speed, and format. Then inspect routing metadata before deciding what produced the result.

estimatedCost is an implementation estimate, not an invoice. durationSeconds describes the returned audio rather than a fixed entitlement. A route reason can explain why automatic selection changed provider or used fallback. If the expected hosted provider was not used, do not present the clip as that provider’s output.

For transcription, review the text against the source audio and mark uncertainty manually. The transcription workbench does not support claims about speaker separation, timing precision, language detection, or a guaranteed export format.

Save the audio only according to the current product and organizational handling rules. The approved documentation does not promise a fixed retention period for generated clips, transcripts, sessions, or usage records. When the text contains private material, consider whether a local route is genuinely local before relying on the product name as a privacy guarantee.

The returned metadata explains what produced the audio and whether the route changed during execution. Enter a short text sample, select a supported output format, and keep speed near the default for the first request. A successful audio response proves that one request completed; it does not establish durable session persistence or universal provider readiness.

Troubleshooting

Start with the stage that failed:

• The request is rejected immediately. Check that text is present, no longer than 5,000 characters, the format is mp3, wav, or opus, and speed is within 0.1–10.
• The provider reports setup required. Open Voice settings and confirm server-side provider configuration. Do not place provider secrets in the client request.
• Private mode is unavailable. Install and start a compatible local speech runtime, then verify that the product detects it.
• The voice sounds like a test voice. Inspect fallbackUsed, routeReason, and provider; automatic routing may have used mock output.
• No usage entry appears. Generation logging is best effort, so absence of a record does not by itself prove request failure.
• Transcription options are unclear. Follow the current transcription surface and avoid assuming undocumented endpoint fields or outputs.

Retry after correcting the identified cause. Repeated submissions do not configure a provider, install a runtime, or expand a preview capability. When reporting a persistent speech failure internally, include the chosen routing mode, provider, model, format, returned error, and whether fallback was reported; do not include credentials or sensitive source text.

After the first successful request, vary one control at a time. Test a different format before changing the provider, or change the voice before changing routing mode. Isolating variables makes it easier to determine whether a difference comes from synthesis settings, provider behavior, automatic fallback, or playback support.

Most first-request failures can be separated into validation, setup, routing, local-runtime, or provider categories.