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

# List Voices

> List all available voices including cloned voices

Retrieve all voices available for your AI agents, including built-in voices and your custom cloned voices.

## Request Body

<ParamField body="provider" type="string">
  Filter by provider: `openai` or `elevenlabs`.
</ParamField>

<ParamField body="include_builtin" type="boolean" default={true}>
  Whether to include built-in voices in the response.
</ParamField>

## Response

<ResponseField name="voices" type="array">
  Array of voice objects.
</ResponseField>

### Voice Object

<ResponseField name="id" type="string">
  Voice identifier to use in agent configuration.
</ResponseField>

<ResponseField name="name" type="string">
  Voice display name.
</ResponseField>

<ResponseField name="provider" type="string">
  Voice provider: `openai` or `elevenlabs`.
</ResponseField>

<ResponseField name="preview_url" type="string">
  URL to preview the voice (if available).
</ResponseField>

<ResponseField name="is_custom" type="boolean">
  Whether this is a custom cloned voice.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/list-voices \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/list-voices',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    }
  );

  const { voices } = await response.json();
  console.log('Available voices:', voices.length);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/list-voices',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={}
  )

  data = response.json()
  for voice in data['voices']:
      print(f"{voice['name']} ({voice['provider']})")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "voices": [
      {
        "id": "21m00Tcm4TlvDq8ikWAM",
        "name": "Rachel",
        "description": "Calm, American female",
        "provider": "elevenlabs",
        "is_custom": false
      },
      {
        "id": "pNInz6obpgDQGcFmaJgB",
        "name": "Adam",
        "description": "Deep, American male",
        "provider": "elevenlabs",
        "is_custom": false
      },
      {
        "id": "EXAVITQu4vr4xnSDxMaL",
        "name": "Sarah",
        "description": "Soft, American female",
        "provider": "elevenlabs",
        "is_custom": false
      },
      {
        "id": "openai-alloy",
        "name": "Alloy",
        "description": "Neutral, professional",
        "provider": "openai",
        "is_custom": false
      },
      {
        "id": "openai-nova",
        "name": "Nova",
        "description": "Bright, energetic",
        "provider": "openai",
        "is_custom": false
      },
      {
        "id": "abc123xyz",
        "name": "My Cloned Voice",
        "description": "Custom cloned voice",
        "provider": "elevenlabs",
        "preview_url": "https://api.elevenlabs.io/v1/voices/abc123xyz/preview.mp3",
        "is_custom": true
      }
    ]
  }
  ```
</ResponseExample>