Render one bounded managed voice-selector preview

An explicit Listen action for one selected TTS voice. It accepts a bounded caller sentence (defaulting to a short product sample only when no audio_environment is supplied), keeps no audio or telemetry, and returns a short in-memory WAV only. A selected outgoing audio_environment requires explicit non-blank text and makes a deterministic, headroom-safe local audition; it never substitutes the text, language, voice, or claims a receiver-side final mix. A small per-workspace fixed-window limit protects provider spend. Every language a provider advertises can be previewed. On a platform credential the voice must be one the workspace could browse and select, except an existing saved hosted agent may re-test its exact current platform-managed selection by supplying agent_id when it has disappeared from a listing; arbitrary typed IDs never create shared runtime evidence. With a selected BYOK credential the credential is validated at the provider and then used to render, so any voice id that provider accepts works, and a platform credential is never a fallback. A GPT-Live-1 voice (provider openai, model gpt-live-1) previews differently: it is a short real live session on the platform credential that speaks Skysay's own sample sentence for the requested language, rendered once per voice, language and sample and then served from a tenant-agnostic cache (the response carries text_source: platform_sample and cached). Typed text is refused with error code voice_preview_fixed_sample rather than replaced, credential_id and delivery do not apply, a platform-wide concurrency cap answers 429 when every preview slot is busy, and the preview is never metered as a call.

post/v1/voice-previews

Request

  • Base URL: https://api.skysay.ai
  • URL: https://api.skysay.ai/v1/voice-previews
  • Auth: none declared

Request body

agent_idstring

Optional saved hosted agent pin for a managed preview only. It must belong to the authenticated project and exactly match the requested platform-managed provider, model, voice id, and language. It permits re-testing a stored selection missing from the current provider listing; it does not authorize a new voice choice or any BYOK selection.

credential_idstring

Optional selected BYOK credential. It is validated at the provider and then used to render this preview; a platform credential is never a fallback.

delivery'natural' | 'lively' | 'calm' | 'precise'

Optional delivery profile, the same value an agent stores in voice_polish.delivery. The preview applies exactly the provider settings a call with that profile would use; for a provider/model without a truthful control (Fish Audio, Azure) the audio is unchanged and the response reports delivery_applied: false.

languagestring required

Any language the selected provider advertises.

modelstring required
organization_idstring

Optional consistency hint; if supplied, it must match the bearer workspace.

project_idstring required

Must belong to the bearer workspace.

providerstring required
textstring

Optional sentence to speak. Omitted or blank falls back to a short product sample only when no audio_environment is supplied. With an audio_environment it is required and must be non-blank, so the requested text is never silently replaced. It is synthesized, never stored, and never echoed in the response.

voice_idstring required

Exact provider voice id. On a platform credential it must be present in the browsable voice inventory, except an existing saved hosted agent may explicitly re-test its exact current selection; with a BYOK credential any id the provider accepts is allowed, so cloned and private voices work.

Response

Bounded base64-encoded WAV preview

Changes

No recorded changes to this operation across all 1 revision of this API.