External Voices

Bring your own ElevenLabs, OpenAI, or Google voices into ToneBoard projects

Overview

External voices come from third-party text-to-speech providers, connected with your own provider account and API key. ToneBoard stores the provider credentials encrypted, lists the voices your account can use, and routes generation through the provider when a character speaks. Provider usage is billed by the provider to your account; ToneBoard charges tokens only for its own processing.

Three concepts fit together:

Concept	What it is
Voice Provider	A connection to a provider account (e.g. your ElevenLabs key). Managed in Voice Providers.
Voice	A provider voice adopted into one of your projects, with your own name for it. Managed in Voices.
Character	A persona that binds a voice (external or internal) to tone instructions. Characters with external voices have `external: true`.

Supported Providers

Provider	Voices	Notable settings
ElevenLabs	Your account's voice library, including cloned and community voices	stability, similarity boost, speaker boost; SSML supported
OpenAI	The fixed set: alloy, echo, fable, onyx, nova, shimmer	speed (0.25-4.0), model (tts-1 / tts-1-hd)
Google	The full Google Cloud TTS catalog (WaveNet, Neural2, ...)	speaking rate, pitch, volume gain; SSML supported
Resemble	Your Resemble project voices	—

Connecting a Provider

1Get an API key from the provider (e.g. your ElevenLabs profile → API keys).
2In Voice Providers, choose New Provider, pick the provider type, name the connection, and paste the key.
3The key is encrypted at rest and never shown again in full or exposed through the API.

Adding Voices to a Project

1Go to Voices and choose New Voice.
2Select the project and the provider connection; ToneBoard fetches the voices available to your account.
3Pick a provider voice, give it a name meaningful to your team, and save.

Then create a character with that voice. Characters using external voices support SSML-based expression enhancement when the provider supports it.

Deleting is guarded

A voice cannot be deleted while characters use it, and a character cannot be deleted while live endpoints use it — the dashboard and API both report what is blocking the delete.

Token Costs

Operation	Cost (tokens)
TTS generation with an external voice	5
Public TTS API with an external voice	5

Provider-side usage (e.g. ElevenLabs character quota) is billed separately by the provider.

API Access

With the external_voices:read scope a key can list providers and browse their voices; voices:read / voices:write cover project voices.

GET/api/v1/voice-providersexternal_voices:read

GET/api/v1/external-voices?voiceProviderId={'{id}'}external_voices:read

GET/api/v1/voices?projectId={'{id}'}voices:read

POST/api/v1/voicesvoices:write

DELETE/api/v1/voices/{'{id}'}voices:write

Browse a provider's voices and adopt one into a project:

# 1. Find your provider connection id
curl -s https://<host>/api/v1/voice-providers -H "Authorization: Bearer $API_KEY"

# 2. List the voices that provider offers
curl -s "https://<host>/api/v1/external-voices?voiceProviderId=<providerId>" \
  -H "Authorization: Bearer $API_KEY"

# 3. Create a project voice from one of them
curl -s https://<host>/api/v1/voices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Narrator",
    "projectId": "<projectId>",
    "voiceProviderId": "<providerId>",
    "externalVoiceId": "<voice_id from step 2>"
  }'

Creating an external character

When creating a character via the API with a project voice, set external: true so ToneBoard resolves the voice against the right store:

curl -s https://<host>/api/v1/characters \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Narrator",
    "projectId": "<projectId>",
    "voiceId": "<project voice id>",
    "external": true,
    "characterDefinition": "Calm, measured documentary narrator."
  }'