Voice management

Save, organize, reuse, and test voices across providers from one Speechbase workspace.

Voice management is how Speechbase turns provider-specific voice identifiers into reusable workspace assets. Instead of hardcoding provider, model, voice ID, and provider-specific options in every request, save them once and call the voice by its Speechbase ID.

What a saved voice stores

A saved voice contains:

Field	Why it matters
`provider`	The upstream provider to call, such as `openai`, `elevenlabs`, or `cartesia`.
`model`	The provider model ID to use with this voice.
`voice_id`	The provider-native voice identifier used during synthesis.
`provider_options`	Optional provider-specific settings such as stability, similarity boost, language, speed, or style.
Metadata	Title, description, tags, and gender labels for dashboard organization.

When a synthesis request uses mode: "voice", Speechbase loads the saved row, merges voice-level provider_options with request-level overrides, and routes to the resolved provider/model/voice.

Save a catalog voice

Open Voices in the dashboard.
Browse the trending or catalog voices.
Save the voice to your workspace.
Rename it, add tags, or add notes for your team.

You can also save a voice directly from the Audio Playground after auditioning it.

Import a provider voice

If you already know a provider's voice ID, import it manually:

Open Voices -> Library.
Click Add New Voice.
Choose the provider and model.
Paste the provider-native voice_id.
Add optional metadata and provider options.

This is useful when you already have custom voices in a provider dashboard and want your application to reference them through Speechbase.

Use a saved voice from the API

{
  "mode": "voice",
  "voiceId": "01940f8a-2dc1-7000-9b6c-fc6dd8a0a4d2",
  "text": "This request uses the saved provider, model, and voice settings.",
  "output": "mp3"
}

Saved voices are scoped to your organization. A voice ID from one workspace cannot be used by another workspace.

Override provider options per request

Voice-level provider options act as defaults. Request-level options override them for a single call:

{
  "mode": "voice",
  "voiceId": "01940f8a-2dc1-7000-9b6c-fc6dd8a0a4d2",
  "text": "Make this one a little faster.",
  "providerOptions": {
    "speed": 1.1
  }
}

Use voice-level options for stable identity and quality settings. Use request-level options for one-off changes.

Voice cloning status

The dashboard includes a voice clone creation flow for collecting reference audio and voice metadata. A cloned voice is only usable for synthesis after it has a provider-native voice_id bound to the saved voice row. Until then, calls using that voice fail with voice_incomplete.

If you already created a custom voice in a provider, import its provider voice ID with Add New Voice.

Pronunciation dictionaries and moderation rulesets are request-level controls. The org default pronunciation dictionary and org default moderation ruleset apply automatically; callers can pass pronunciations.dictionaryIds, inline pronunciation rules, or moderation_ruleset_id when a request needs a different policy.