Voice API

The directly verified Voice API surface is POST /api/voice/speech, which accepts a JSON speech-generation request and returns safe JSON containing base64 audio plus routing metadata. This guide documents that handler rather than inferring a broad public API family from Voice navigation. The route does not establish a dedicated Bearer-token contract, and current limits, routing behavior, and provider readiness remain preview implementation details.

Authentication

The inspected speech handler does not establish a dedicated Authorization: Bearer requirement. Do not copy the AI Gateway authentication model into Voice documentation or client code without a Voice-specific source. The handler applies shared rate and beta-usage policies, but those controls are not the same as a documented public authentication contract.

Provider credentials remain server-side. A client can request a provider or routing mode, but it should not send hosted-provider API keys in the request body. When a hosted adapter lacks server configuration, the expected outcome is a setup-required error rather than client-side credential exchange.

Because the authentication boundary is incomplete, deployers should treat this route according to the access controls of the current Ethen environment. The documentation can state what the handler validates, but it cannot promise anonymous public access, project-scoped keys, user sessions, or a stable external API gateway. Those questions remain covered by authentication-requires-verification.

Clients inside the current application may inherit protection from the surrounding deployment, but that behavior should not be described as part of the Voice API unless the relevant middleware or route guard is supplied. External integrations need an explicit review of who can reach the endpoint, how requests are associated with a user or project, and how abusive traffic is contained.

The absence of a dedicated Bearer contract also means examples should not show a placeholder key. A fabricated header can mislead developers into believing that key issuance, scope, revocation, and audit behavior match the AI Gateway. Those systems have separate contracts and must remain separate in the documentation.

The inspected speech handler does not establish a dedicated Voice Bearer-token requirement. The handler applies a shared speech rate-limit policy and a beta usage-limit key before provider execution. Input is parsed as JSON, sanitized, and validated before routing. Required and optional fields are limited to the inspected request contract: text, provider, model, voiceId, routingMode, format, and speed.

The handler applies a shared speech rate-limit policy and a beta usage-limit key before provider execution; send JSON to POST /api/voice/speech with a non-empty text value. Text longer than 5,000 characters fails validation in the current implementation; decode audioBase64 using the returned format rather than assuming an audio container. Do not add OpenAI-style fields, authorization headers, streaming semantics, or endpoints that are not present in the inspected Voice sources.

Core endpoints

Only one endpoint is directly verified for this guide:

POST /api/voice/speech

The route performs these stages:

1. Apply the shared speech rate policy.
2. Apply a beta usage-limit key.
3. Parse and sanitize JSON.
4. Validate the supported fields.
5. Resolve a provider route.
6. Call the server-side speech adapter.
7. Log usage on a best-effort basis.
8. Return safe JSON containing audio and metadata.

Voice surfaces for transcription, agents, sessions, phone setup, dubbing, usage, and settings exist, but their API contracts were not directly established by the supplied handler set. Do not invent endpoint paths for them or infer that they accept the same fields as speech generation.

The current 5,000-character validation and rate controls describe the implementation inspected on 2026-07-11. They should not be published as permanent commercial limits without product review.

The route is response-oriented rather than session-oriented. It returns one generated result for one submitted body and does not expose a verified session-creation, session-resume, or streaming endpoint. If a product surface stores history around the request, that UI behavior should not be converted into additional API methods without source evidence.

Routing is part of endpoint behavior, not a second endpoint family. A provider value requests a particular adapter, while a routing mode expresses selection policy. The server can reject an unconfigured route, choose another eligible path, use mock fallback, or report that private mode lacks a local runtime.

Only one endpoint is directly verified for this guide: POST /api/voice/speech. Text longer than 5,000 characters fails validation in the current implementation. Valid formats are mp3, wav, and opus; speed values outside 0.1 through 10 are rejected. The server resolves routing, calls an adapter, logs usage best effort, and returns base64 audio in JSON.

Requests

The request body is JSON. text is required. The remaining fields are optional controls supported by the inspected route:

A minimal request is:

{
"text": "Hello from Ethen Voice.",
"routingMode": "balanced",
"format": "mp3",
"speed": 1
}

Do not add fields such as tools, tool choice, response format, penalties, seed, log probabilities, or streaming options. Those fields are not part of the verified speech contract. Likewise, do not assume that a provider, model, or voice listed in static constants is currently healthy.

Sanitization happens before routing, so client applications should still validate their own user experience without assuming that every malformed value reaches a provider. Keep text encoding predictable, avoid sending unrelated object properties, and treat an empty or whitespace-only input as invalid even before the server responds.

Provider, model, and voice values are identifiers within the current configuration. The repository bundle does not publish a permanent enumeration for external consumers. A robust client should therefore obtain choices from the current product surface or configuration rather than hardcoding the examples found in constants.

Speech requests use a narrow JSON contract with text plus optional routing and output controls. Response metadata includes identity, provider, model, voice, format, duration, estimated cost, fallback state, route reason, and creation time. No general Voice Bearer-authentication contract was verified in the speech handler. Decode audioBase64 using the returned format rather than assuming an audio container.

Responses

A successful response contains base64-encoded audio and metadata. Verified response concepts include:

Decode audioBase64 according to the returned format; do not assume MP3 when the request or route selected another container. Use provider, fallbackUsed, and routeReason together to identify the execution path. Automatic routing can return mock output when hosted providers are not configured, and private routing can report unavailable when no local runtime is installed.

Usage logging is best effort. A valid response does not guarantee that an immutable usage record was created, and a missing usage entry does not retroactively invalidate the audio.

The audio payload can be large because it is embedded in JSON. The supplied handler establishes this representation but does not define a streaming or binary-download alternative. Clients should avoid logging the full base64 value and should release decoded audio objects when they are no longer needed.

estimatedCost and durationSeconds are useful for display and diagnosis, but neither should drive billing settlement or a contractual limit. The route can also complete while best-effort usage logging fails, so downstream systems must not assume a one-to-one relationship between returned audio and a durable usage row.

Successful responses carry base64 audio and metadata that identifies routing, format, duration, and fallback. Inspect fallbackUsed and routeReason before attributing the response to the requested provider. Handle validation, setup-required, local-unavailable, rate-limit, routing, and provider failures as distinct conditions. Send JSON to POST /api/voice/speech with a non-empty text value.

Errors

Errors should be handled by stage rather than collapsed into one retry loop.

• Validation failure: text is missing, exceeds the current maximum, format is unsupported, speed is outside the accepted range, or JSON cannot be used.
• Setup required: the selected hosted provider lacks server-side configuration.
• Local unavailable: private routing was requested without a detected local speech runtime.
• Routing failure: no eligible route could satisfy the request.
• Provider failure: the selected adapter returned an operational error.
• Rate or beta-usage failure: the current shared policy rejected the request.

Correct validation and configuration problems before retrying. Repetition does not install a runtime or create provider credentials. When automatic routing succeeds through mock fallback, the result is not an error, but the client should disclose that it did not come from the requested hosted provider.

Return error details safely. Do not expose provider secrets, internal stack traces, or sensitive submitted text in client-visible diagnostics.

Preserve the distinction between retryable and non-retryable causes. A transient provider failure may justify another attempt after the environment recovers. Invalid text, unsupported format, missing provider configuration, or unavailable private routing requires a change in request or setup. Blind retries increase load without changing those conditions.

For internal diagnosis, capture the result ID when present, requested and returned provider information, routing mode, route reason, fallback state, format, and safe error details. Exclude provider keys, full sensitive text, and base64 audio from routine logs.

The handler can reject a request before provider execution or return a setup, routing, local, rate, or adapter failure. Add provider, model, voice, routing mode, format, or speed only when the chosen surface supports those values.

Examples

A request with explicit output controls can remain within the verified contract:

{
"text": "Your report is ready for review.",
"provider": "mock",
"format": "wav",
"speed": 0.95
}

A client-side outline is:

1. Serialize the supported JSON fields.
2. POST the body to /api/voice/speech.
3. Parse the JSON response.
4. If audioBase64 is present, decode it using format.
5. Display provider, routeReason, and fallbackUsed with the result.
6. Map validation, setup, local, routing, rate, and provider errors separately.

The example intentionally omits an authorization header because the inspected handler does not define one. It also avoids undocumented Voice endpoints and fields. Before using the route outside the current Ethen application, verify the environment’s access control, deployment base URL, rate policy, provider configuration, and handling of generated audio.

A production client should also define how decoded audio is stored, displayed, expired, and removed. Those responsibilities are outside the verified handler contract. The approved legal links do not establish a Voice-specific retention period, so integrations must avoid promising that generated audio or request metadata will be kept or deleted on a fixed schedule.

A minimal example should use only fields implemented by the inspected handler. The current rate-limit and character validation describe repository behavior on the verification date, not a permanent commercial entitlement.