# 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: Array[{ id, description, language, 2 more}]`

    - `id: String`

      The ID of the voice.

    - `description: String`

      The description of the voice.

    - `language: :en | :fr | :es | 5 more`

      The language of the voice.

      - `:en`

      - `:fr`

      - `:es`

      - `:de`

      - `:it`

      - `:pt`

      - `:ru`

      - `:zh`

    - `name: String`

      The name of the voice.

    - `provider: :cartesia | :elevenlabs`

      The provider of the voice.

      - `:cartesia`

      - `:elevenlabs`

### Example

```ruby
require "revox"

revox = Revox::Client.new(api_key: "My API Key")

voices = revox.voices.list

puts(voices)
```

## Retrieve

`voices.retrieve(id, **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: String`

- `provider: :cartesia | :elevenlabs`

  - `:cartesia`

  - `:elevenlabs`

### Returns

- `class VoiceRetrieveResponse`

  - `voice: { id, name, description}`

    - `id: String`

    - `name: String`

    - `description: String`

### Example

```ruby
require "revox"

revox = Revox::Client.new(api_key: "My API Key")

voice = revox.voices.retrieve("id", provider: :cartesia)

puts(voice)
```

## Preview

`voices.preview(**kwargs) -> void`

**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: :cartesia | :elevenlabs`

  The provider to use for the preview.

  - `:cartesia`

  - `:elevenlabs`

- `voice_id: String`

  The voice ID to generate a preview for.

### Example

```ruby
require "revox"

revox = Revox::Client.new(api_key: "My API Key")

result = revox.voices.preview(provider: :cartesia, voice_id: "voiceId")

puts(result)
```