Skip to main content

​
Voices

Manage voice configurations and imports from providers (e.g. ElevenLabs). Voices are assigned to agents and determine how the agent sounds on calls. For UUID / phone / datetime formats used below, see Data formats.

​
List Voices

Returns all voices available to your organization (both system voices and custom/cloned voices).

​
cURL

curl "https://api.truedy.ai/api/public/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

data (array of voice objects), meta. 
{
  "data": [
    {
      "id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
      "name": "Support Voice",
      "provider": "elevenlabs",
      "type": "reference",
      "language": "en-US",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "f98eb11f-9f34-4d13-9075-0e29f106f37d",
    "ts": "2024-01-01T00:00:00Z"
  }
}

​
Get Voice

​
cURL

curl "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Import Voice from Provider

Import an existing voice from ElevenLabs (or another provider) into your organization. Use this when you already have a voice ID from a provider and want to use it with your agents.

​
Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the voice in your dashboard
providerstringNoVoice provider. Default: elevenlabs
provider_voice_idstringYesThe voice ID from your provider (e.g. ElevenLabs voice ID)

​
Example

{
  "name": "Support Voice",
  "provider": "elevenlabs",
  "provider_voice_id": "21m00Tcm4TlvDq8ikWAM"
}

​
cURL

curl -X POST "https://api.truedy.ai/api/public/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Voice",
    "provider": "elevenlabs",
    "provider_voice_id": "21m00Tcm4TlvDq8ikWAM"
  }'
Response: 201 Created with data (voice object) and meta. May return 422 or 502 if the provider rejects the request (e.g. invalid voice ID or quota exceeded).

​
Clone Voice from Audio

Create a voice clone from your own audio samples. Upload one or more audio files (base64-encoded), and the system will clone the voice via ElevenLabs and import it to Ultravox for use with agents. Requires credits on your account.

​
Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the cloned voice (max 40 characters)
filesobject[]YesOne or more audio files. Each file is { filename, data, content_type }
files[].filenamestringYesFile name including extension (e.g. sample.mp3)
files[].datastringYesBase64-encoded audio file content
files[].content_typestringNoMIME type. Default: audio/mpeg. Supports: audio/mpeg, audio/wav, audio/mp4, audio/x-m4a
Tips for best results:
  • Use 1–5 minutes of clear, noise-free audio
  • Avoid music or background noise
  • MP3 or WAV at 44.1kHz works best

​
Example

{
  "name": "My Custom Voice",
  "files": [
    {
      "filename": "sample.mp3",
      "data": "<base64-encoded audio bytes>",
      "content_type": "audio/mpeg"
    }
  ]
}

​
cURL

# Encode your audio file to base64 first:
# base64 -i sample.mp3 > sample_b64.txt

curl -X POST "https://api.truedy.ai/api/public/v1/voices/clone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Voice",
    "files": [
      {
        "filename": "sample.mp3",
        "data": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA...",
        "content_type": "audio/mpeg"
      }
    ]
  }'
Response: 201 Created with data (voice object with status: "active") and meta. The voice is immediately ready for use. Returns 422 if name exceeds 40 characters or no files are provided. Returns 402 if your account lacks sufficient credits.

​
Update Voice

Update the display name of a voice. The name is passed as a query parameter.

​
Parameters

Query parameters:
ParameterTypeRequiredDescription
namestringYesNew display name for the voice

​
cURL

curl -X PATCH "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5?name=Support+Voice+V2" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Delete Voice

Deletes the voice from your organization. Agents using this voice will need to be updated.

​
cURL

curl -X DELETE "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Sync Voice

Re-syncs a voice with Ultravox (the underlying AI platform). Use this if a voice shows as inactive or if you encounter sync errors. May return 422 if the sync fails (e.g. provider error).

​
cURL

curl -X POST "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5/sync" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Preview Voice

Generate a short audio preview of the voice speaking a given text. Returns raw WAV audio bytes.

​
Parameters

Query parameters:
ParameterTypeDescription
textstringText for the voice to speak. Defaults to a standard greeting if omitted.

​
cURL

curl "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5/preview?text=Hello%20from%20Truedy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o preview.wav
Returns raw WAV audio. May return 422 or 502 if the provider fails.

​
Voice Object

FieldTypeDescription
idUUIDVoice ID
namestringDisplay name
providerstringProvider: elevenlabs, google, azure, openai
typestringreference (imported) or custom (cloned)
languagestringLanguage code (e.g. en-US)
statusstringactive, training, or failed
created_atdatetimeWhen the voice was added
updated_atdatetimeLast updated