> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List all Voices

> Retrieves a comprehensive list of all available voices, including public voices, shared voices, and custom-created voices. Each voice entry provides detailed attributes such as a unique identifier, voice name, gender, and age, ensuring precise selection and usability.

## 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

```json [expandable] theme={null}
{
  "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": 147320,
      "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`](create-tts) endpoint to generate speech with your selected voice
* Use the [`/voices/create-custom-voice`](create-custom-voice) endpoint to add new voices to this list
* Use the [`/text-to-voice`](create-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.


## OpenAPI

````yaml get /list-voices
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /list-voices:
    get:
      tags:
        - Apis
      summary: List Voices
      operationId: list-voices_list-voices_get
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVoice'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ListVoice:
      type: array
      items:
        $ref: '#/components/schemas/VoiceItem'
      title: ListVoice
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VoiceItem:
      properties:
        id:
          type: integer
          title: ID
          description: >-
            A unique identifier for the voice record. This ID serves as the
            primary reference when using the voice in other API operations.
        voice_name:
          type: string
          title: Voice Name
          description: >-
            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:
          type: integer
          nullable: true
          title: Gender
          description: >-
            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:
          type: integer
          nullable: true
          title: Age
          description: >-
            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:
          type: string
          nullable: true
          title: Description
          default: null
          description: >-
            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:
          type: string
          nullable: true
          title: Transcript
          default: null
          description: >-
            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:
          type: boolean
          nullable: true
          title: Is Published
          description: >-
            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:
          $ref: '#/components/schemas/Languages'
          title: Language
          default: null
          description: >-
            The language associated with the voice. This is particularly
            important for ensuring proper pronunciation and natural speech
            patterns.
      type: object
      title: VoiceItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Languages:
      type: integer
      enum:
        - 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
      title: Languages
      default: 1
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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.

````