Get Voice Preview

Fetch ready-to-play preview audio for one voice in one language. Returns the voice's `name`, the preview's `locale`, the `model` it was synthesized with, its stored `content_type`, and a `sample_url` — a time-limited presigned URL valid for 1 hour; regenerate it by calling this endpoint again rather than caching it long-term. Pass `model` to prefer a specific TTS model; a preview from another model is still returned when that model has none. `language` accepts a bare family (`ko`, `en`) as well as an exact locale (`ko-kr`, `en-gb`). A bare family expands to every supported locale in it, and which region wins is deterministic but arbitrary — so the response echoes the `locale` actually served. Read `locale`, never the request parameter, when labelling what the caller is hearing. 404 means no preview audio has been generated for this voice in that locale — NOT that the voice cannot speak it. `supported_languages` on the voice is the claim about what it can speak; `preview_locales` is the list of locales this endpoint will succeed for. 404 is also returned when the voice does not exist, is not accessible to the caller's workspace, or is a platform voice from a provider that is not available to your account.

Authentication

AuthorizationBearer
Clerk JWT token
OR
AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Path parameters

voice_idstringRequiredformat: "uuid"

Headers

X-Workspace-Idstring or nullOptional

Query parameters

languageenumRequired

BCP-47 language code, e.g. en-us, ko-kr

modelstring or nullOptional

TTS model id, e.g. sonic-2

Response

Successful Response
dataobject
metaobject

Errors

422
Unprocessable Entity Error