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

200
application/json

Successful Response

The response is of type VoiceItem · object[].