Skip to main content
GET
/
list-voices
List Voices
curl --request GET \
  --url https://client.camb.ai/apis/list-voices \
  --header 'x-api-key: <api-key>'
[
  {
    "id": 123,
    "voice_name": "<string>",
    "gender": 123,
    "age": 123,
    "description": null,
    "transcript": null,
    "is_published": true,
    "language": null
  }
]

​
Understanding the Voice Ecosystem

This endpoint serves as your gateway to our platform’s complete voice library, providing a unified view of all voices available to your account. The returned collection includes three distinct categories of voices:
  1. Public Voices: These are system-provided voices available to all users. They offer professional-quality speech synthesis across multiple languages, accents, and demographic characteristics.
  2. Custom Voices: These are unique voices you’ve created using our voice cloning technology. Custom voices allow you to maintain brand consistency or create specific character voices for your applications.
  3. Shared Voices: These are voices created by other users who have chosen to make them available on the marketplace. Shared voices expand your options without requiring you to create custom voices from scratch.
By accessing this comprehensive catalog, you can explore the full range of vocal options before deciding which voice best suits your specific use case.

​
Using the Endpoint

To retrieve the list of all available voices, simply send a GET request to this endpoint: 
GET /list-voices
No parameters are required for this request. The system will return an array containing detailed information about each available voice.

​
Example Response

{
  "voices": [
    {
      "id": 20305,
      "voice_name": "Alice",
      "gender": 2,
      "age": 65,
      "language": 1,
      "transcript": null,
      "description": "A warm, steady voice with a calm tone and a touch of enthusiastic energy, perfect for engaging narration.",
      "is_published": false
    },
    {
      "id": 20299,
      "voice_name": "Gary",
      "gender": 1,
      "age": 35,
      "language": 1,
      "transcript": null,
      "description": "A rich, warm voice brimming with emotion and dynamic expression, perfect for dramatic readings that captivate the listener.",
      "is_published": false
    }
    // Additional voice entries...
  ]
}

​
Voice Selection Best Practices

When working with the voice catalog, consider these approaches to ensure optimal results:

​
1. Filter Locally for Specific Requirements

Since the endpoint returns all available voices, implement client-side filtering to narrow down options based on your specific requirements. Common filtering criteria include:
  • Gender: Filter based on whether you need male, female, or gender-neutral voices
  • Age range: Select voices within specific age brackets to match your target audience
  • Language: Filter for voices that support the languages your content requires
  • Publication status: Distinguish between private and publicly shared voices

​
2. Implement Voice Previews

Before committing to a specific voice for your project, provide users with the ability to preview different voices using small audio samples. This can be accomplished by:
  1. Selecting a subset of voices from the catalog that match your initial criteria
  2. Using the text-to-speech endpoint with a short, consistent text sample for each voice
  3. Presenting these samples to users or stakeholders to gather feedback

​
3. Consider Voice Consistency

When building applications with extensive voice interaction:
  • Maintain consistency by using the same voice throughout a user journey
  • Document your selected voice IDs in your application configuration
  • Consider creating backup voice selections in case primary choices become unavailable

​
4. Optimize for Different Content Types

Different voice characteristics work better for different types of content:
  • Informational content: Clear, measured voices with neutral emotional tones
  • Narrative content: Expressive voices with good dynamic range
  • Instructional content: Patient, articulate voices with excellent clarity
  • Conversational interfaces: Natural, friendly voices with appropriate pacing

​
Relationship with Other Endpoints

The /list-voices endpoint works in conjunction with several other endpoints in the API:
  • Use this endpoint to discover available voices
  • Use the /tts endpoint to generate speech with your selected voice
  • Use the /voices/create-custom-voice endpoint to add new voices to this list
  • Use the /text-to-voice endpoint to generate voices from text descriptions
This interconnected system of endpoints gives you complete control over voice discovery, creation, and utilization across your applications.

Authorizations

​
x-api-key
string
header
required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Response

Successful Response

​
id
integer

A unique identifier for the voice record. This ID serves as the primary reference when using the voice in other API operations.

​
voice_name
string

The name or label assigned to the voice. For public voices, this typically indicates the voice character (e.g., 'Sarah' or 'Michael'). For custom voices, this is the name you provided during creation.

​
gender
integer | null

Represents the gender of the voice, encoded as an integer value. Common values include 1 for male and 2 for female, though other values may be used to represent non-binary or other gender identities.

​
age
integer | null

The approximate age of the voice, represented as an integer. This helps you select voices that match your desired demographic characteristics. May be null if age information is not available.

​
description
string | null

A brief summary describing the custom voice's characteristics—such as its tone, emotional quality, or intended use cases. This field provides context beyond the basic demographic information. May be null for voices without descriptions.

​
transcript
string | null

The transcribed text of the source recording used to create custom voices. This can be helpful to understand the vocal range and quality demonstrated in the original sample. May be null if no transcript is available.

​
is_published
boolean | null

Indicates whether the voice is shared on the marketplace (true) or private to your account (false). This allows you to identify shared voices that others can access.

​
language
enum<integer>

The language associated with the voice. This is particularly important for ensuring proper pronunciation and natural speech patterns.

Available options:
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21,
22,
23,
24,
25,
26,
27,
28,
29,
30,
31,
32,
33,
34,
35,
36,
37,
38,
39,
40,
41,
42,
43,
44,
45,
46,
47,
48,
49,
50,
51,
52,
53,
54,
55,
56,
57,
58,
59,
60,
61,
62,
63,
64,
65,
66,
67,
68,
69,
70,
71,
72,
73,
74,
75,
76,
77,
78,
79,
80,
81,
82,
83,
84,
85,
86,
87,
88,
89,
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
100,
101,
102,
103,
104,
105,
106,
107,
108,
109,
110,
111,
112,
113,
114,
115,
116,
117,
118,
119,
120,
121,
122,
123,
124,
125,
126,
127,
128,
129,
130,
131,
132,
133,
134,
135,
136,
139,
140,
141,
142,
143,
144,
145,
146,
147,
148,
149,
150