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

# ElevenLabs Voices

> Discover the voices available in Sunra's shared ElevenLabs account, and use any of them in any ElevenLabs TTS model via custom_voice_id.

# Listing ElevenLabs Voices

Sunra exposes a lightweight helper endpoint that lets you discover the voices available on the shared ElevenLabs account that powers our ElevenLabs TTS models. The endpoint does not run an inference pipeline — there is no billing, no prediction record, no queue. It is a direct, paginated lookup against the upstream ElevenLabs voice library.

Once you find a voice you like, plug its `voice_id` into the `custom_voice_id` field of any ElevenLabs TTS model and the model will use that voice instead of its default.

## Endpoint

```
GET https://api.sunra.ai/v1/elevenlabs/voices
```

Authentication is the same as the rest of the Sunra API — send your API key in the `Authorization` header.

## Query parameters

All parameters are optional.

| Parameter         | Type / values                                                                                        | Default | Description                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| `page_size`       | integer (max 100)                                                                                    | 10      | How many voices to return in one response.             |
| `search`          | string                                                                                               | —       | Filter by name, description, labels, or category.      |
| `sort_by`         | `name` \| `date`                                                                                     | —       | Field to sort by. `date` sorts by voice creation time. |
| `sort_direction`  | `asc` \| `desc`                                                                                      | —       | Sort order.                                            |
| `category`        | `premade` \| `cloned` \| `generated` \| `professional`                                               | —       | Voice category.                                        |
| `voice_type`      | `personal` \| `community` \| `default` \| `workspace` \| `non-default` \| `non-community` \| `saved` | —       | Voice ownership / source.                              |
| `next_page_token` | string                                                                                               | —       | Pagination token returned by a previous response.      |

## Response

```json theme={null}
{
  "voices": [
    {
      "voice_id": "9BWtsMINqrJLrRacOk9x",
      "name": "Aria",
      "settings": null
    },
    {
      "voice_id": "CwhRBWXzGAHq8TQ4Fs17",
      "name": "Roger",
      "settings": null
    }
  ],
  "has_more": true,
  "next_page_token": "RVhBVklUUXU0dnI0eG5TRHhNYUx8"
}
```

| Field               | Description                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `voices[].voice_id` | The ID to pass as `custom_voice_id` to a TTS model.                                                      |
| `voices[].name`     | Human-readable voice name.                                                                               |
| `voices[].settings` | Default voice settings (`stability`, `similarity_boost`, etc.) or `null` if none are saved on the voice. |
| `has_more`          | `true` while more pages remain.                                                                          |
| `next_page_token`   | Pass this as `next_page_token` in the next call to fetch the next page. `null` on the last page.         |

## Pagination

Drive pagination from `has_more` and `next_page_token`. Keep calling the endpoint with the previous response's `next_page_token` until `has_more` is `false`:

```javascript theme={null}
let token = undefined;
const all = [];

do {
  const url = new URL("https://api.sunra.ai/v1/elevenlabs/voices");
  url.searchParams.set("page_size", "100");
  if (token) url.searchParams.set("next_page_token", token);

  const resp = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SUNRA_KEY}` },
  });
  const body = await resp.json();
  all.push(...body.voices);
  token = body.has_more ? body.next_page_token : null;
} while (token);
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer $SUNRA_KEY" \
    "https://api.sunra.ai/v1/elevenlabs/voices?category=premade&sort_by=date&sort_direction=desc&page_size=20"
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch(
    "https://api.sunra.ai/v1/elevenlabs/voices?category=premade&sort_by=name&page_size=20",
    { headers: { Authorization: `Bearer ${process.env.SUNRA_KEY}` } }
  );
  const { voices, has_more, next_page_token } = await resp.json();
  console.log(voices.map((v) => `${v.name} (${v.voice_id})`));
  ```

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

  resp = requests.get(
      "https://api.sunra.ai/v1/elevenlabs/voices",
      params={
          "category": "premade",
          "sort_by": "name",
          "page_size": 20,
      },
      headers={"Authorization": f"Bearer {os.environ['SUNRA_KEY']}"},
  )
  data = resp.json()
  for v in data["voices"]:
      print(v["name"], v["voice_id"])
  ```
</CodeGroup>

## Using a voice in a TTS model

Take any `voice_id` from the response and pass it as `custom_voice_id` when calling an ElevenLabs TTS endpoint. When `custom_voice_id` is set it overrides the model's default `voice` field, so you can use any voice the account has access to — including cloned voices and voices saved from the ElevenLabs voice library, not just the defaults exposed by the schema's `voice` enum.

This works for every Sunra ElevenLabs TTS endpoint:

* `elevenlabs/eleven-v3/text-to-speech`
* `elevenlabs/multilingual-v2/text-to-speech`
* `elevenlabs/turbo-v2.5/text-to-speech`
* `elevenlabs/multilingual-sts-v2/speech-to-speech`

```javascript theme={null}
import { sunra } from "@sunra/client";

const result = await sunra.subscribe(
  "elevenlabs/multilingual-v2/text-to-speech",
  {
    input: {
      text: "Welcome to Sunra.",
      custom_voice_id: "9BWtsMINqrJLrRacOk9x",
    },
  }
);
```

```python theme={null}
import sunra_client

result = sunra_client.subscribe(
    "elevenlabs/multilingual-v2/text-to-speech",
    arguments={
        "text": "Welcome to Sunra.",
        "custom_voice_id": "9BWtsMINqrJLrRacOk9x",
    },
)
```