# Voices

## List

`voices.list()  -> VoiceListResponse`

**get** `/voices`

Retrieve the full catalog of voices available for AI calls. The list includes voices from Cartesia and ElevenLabs, each with a name, language, accent, and provider-specific ID. Use this endpoint to browse voices before assigning one to an assistant or a call.

### Returns

- `class VoiceListResponse: …`

  - `voices: List[Voice]`

    - `id: str`

      The ID of the voice.

    - `description: str`

      The description of the voice.

    - `language: Literal["en", "fr", "es", 5 more]`

      The language of the voice.

      - `"en"`

      - `"fr"`

      - `"es"`

      - `"de"`

      - `"it"`

      - `"pt"`

      - `"ru"`

      - `"zh"`

    - `name: str`

      The name of the voice.

    - `provider: Literal["cartesia", "elevenlabs"]`

      The provider of the voice.

      - `"cartesia"`

      - `"elevenlabs"`

### Example

```python
import os
from revox import Revox

client = Revox(
    api_key=os.environ.get("REVOX_API_KEY"),  # This is the default and can be omitted
)
voices = client.voices.list()
print(voices.voices)
```

## Retrieve

`voices.retrieve(strid, VoiceRetrieveParams**kwargs)  -> VoiceRetrieveResponse`

**get** `/voices/{id}`

Retrieve details for a single voice by its unique ID and provider. Returns the voice name, description, and provider metadata.

### Parameters

- `id: str`

- `provider: Literal["cartesia", "elevenlabs"]`

  - `"cartesia"`

  - `"elevenlabs"`

### Returns

- `class VoiceRetrieveResponse: …`

  - `voice: Voice`

    - `id: str`

    - `name: str`

    - `description: Optional[str]`

### Example

```python
import os
from revox import Revox

client = Revox(
    api_key=os.environ.get("REVOX_API_KEY"),  # This is the default and can be omitted
)
voice = client.voices.retrieve(
    id="id",
    provider="cartesia",
)
print(voice.voice)
```

## Preview

`voices.preview(VoicePreviewParams**kwargs)`

**post** `/voices/preview`

Generate a short audio preview for a given voice. Provide the voice ID and provider, and the API returns an audio/mpeg stream you can play back to hear how the voice sounds before assigning it to an assistant.

### Parameters

- `provider: Literal["cartesia", "elevenlabs"]`

  The provider to use for the preview.

  - `"cartesia"`

  - `"elevenlabs"`

- `voice_id: str`

  The voice ID to generate a preview for.

### Example

```python
import os
from revox import Revox

client = Revox(
    api_key=os.environ.get("REVOX_API_KEY"),  # This is the default and can be omitted
)
client.voices.preview(
    provider="cartesia",
    voice_id="voiceId",
)
```