---
title: "Render one bounded managed voice-selector preview"
method: POST
path: "/v1/voice-previews"
---

# Render one bounded managed voice-selector preview

`POST /v1/voice-previews`

## Request

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

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.

## Request body

- VoicePreviewRequest: One short synthesis of a bounded caller sentence for a selected TTS voice. Customer requests bind preview spend to the authenticated workspace; organization_id is an optional consistency hint and a foreign value is rejected.
  - `agent_id` string: 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.
  - `audio_environment` AudioEnvironmentSelection
    - `asset_version` 'v1', required: Immutable packaged asset version; it is never inferred.
    - `preset_id` string, required: Exact catalogue id. `off` has no asset.
    - `volume` integer, required: Whole-number selection. Off requires 0; enabled presets require 1 through 100.
  - `credential_id` string: 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`.
  - `language` string, required: Any language the selected provider advertises.
  - `model` string, required
  - `organization_id` string: Optional consistency hint; if supplied, it must match the bearer workspace.
  - `project_id` string, required: Must belong to the bearer workspace.
  - `provider` string, required
  - `text` string: 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_id` string, 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 `200`

Bounded base64-encoded WAV preview

## Other responses

- `400`: Invalid tenant-bound project, stack, voice, preview text, audio_environment, or a BYOK credential the provider did not accept; also typed text for a GPT-Live-1 voice (voice_preview_fixed_sample)
- `404`: The selected BYOK credential does not exist in this workspace
- `409`: The selected voice cannot be previewed in the requested language
- `429`: Voice-preview fixed-window limit reached, or every platform-wide GPT-Live preview slot is busy
- `503`: Managed preview unavailable

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)