Skip to main content

​
Default voices

OneInbox ships 28 voices out of the box across Cartesia, Deepgram, ElevenLabs, OpenAI, Minimax, and Shisa — no setup needed. You can use any of them immediately by setting tts.voice_id on your agent. Browse the full list (with voice IDs) at any time: 
curl "https://api.oneinbox.ai/v1/voices" \
  -H "Authorization: Bearer <api_key>"

# Filter to one provider
curl "https://api.oneinbox.ai/v1/voices?provider=cartesia" \
  -H "Authorization: Bearer <api_key>"
Always use the id field (vc_...) from the voice object as tts.voice_id — not the provider_voice_id. Passing the raw provider ID (e.g. a Cartesia UUID or a Deepgram model name) returns a VOICE_NOT_FOUND error.

​
How voices work

Every agent has a TTS (text-to-speech) configuration that controls how it sounds. A default voice is automatically assigned when you create an agent — you can hear it immediately with a quick browser call (no phone number needed) or a real phone call. Follow this guide when you want to use a custom voice from ElevenLabs, Cartesia, or another provider. To switch, set the provider and voice_id on the agent. The voice_id is the OneInbox id (vc_abc123) returned when you import a voice (see below). 
curl -X PATCH https://api.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tts": {
      "provider": "elevenlabs",
      "voice_id": "<vc_abc123>"
    }
  }'

​
Step 1 — Add an integration for your provider

If you want to import voices beyond the 28 platform voices, you need to add an integration for your third-party provider first. An integration stores your provider API key securely so OneInbox can authenticate on your behalf.

​
ElevenLabs

curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ElevenLabs",
    "provider": "elevenlabs",
    "api_key": "<elevenlabs_api_key>"
  }'

​
Cartesia

curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cartesia",
    "provider": "cartesia",
    "api_key": "<cartesia_api_key>"
  }'
Both return an integration id — save it for Step 2.

​
Step 2 — Import a voice

Import a specific voice from your provider into OneInbox using its provider voice ID. The provider voice ID is the native ID from your provider’s voice library (not the OneInbox ID). 
curl -X POST https://api.oneinbox.ai/v1/voices/import \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "elevenlabs",
    "provider_voice_id": "21m00Tcm4TlvDq8ikWAM",
    "name": "Rachel",
    "credential_id": "<crd_abc123>",
    "gender": "female",
    "language": "en",
    "accent": "American"
  }'

{
  "id": "vc_abc123",
  "name": "Rachel",
  "provider": "elevenlabs",
  "provider_voice_id": "21m00Tcm4TlvDq8ikWAM"
}
The id field (vc_abc123) is the OneInbox voice ID — this is what you use in the next step when assigning the voice to your agent.

​
Step 3 — Assign the voice to your agent

Use the OneInbox id from the import response (vc_abc123) to assign the voice to your agent. This tells the agent to use that specific voice for all calls. 
curl -X PATCH https://api.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tts": {
      "provider": "elevenlabs",
      "voice_id": "vc_abc123",
      "speed": 1.0
    }
  }'
FieldRangeWhat it does
voice_id—The OneInbox id from the import response (format: vc_abc123)
speed0.5–2.0Playback rate. 1.0 is normal speech speed
stability0.0–1.0Voice consistency. Higher = more consistent tone, lower = more expressive

​
Get a voice

Retrieve a single voice by its OneInbox ID. 
curl https://api.oneinbox.ai/v1/voices/<voice_id> \
  -H "Authorization: Bearer <api_key>"

​
List imported voices

Retrieve all voices in your account, or filter by provider: 
# All voices in your account
curl https://api.oneinbox.ai/v1/voices \
  -H "Authorization: Bearer <api_key>"

# Filter by provider
curl "https://api.oneinbox.ai/v1/voices?provider=elevenlabs" \
  -H "Authorization: Bearer <api_key>"
Each voice object: 
{
  "id": "vc_abc123",
  "name": "Rachel",
  "provider": "elevenlabs",
  "provider_voice_id": "21m00Tcm4TlvDq8ikWAM",
  "gender": "female",
  "language": "en",
  "accent": "American"
}

​
API reference

List voices · Get voice · Import voice