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

# Audio Voices

> Browse the available voice library across both providers. Pick a voice_id for /v1/audio/speech.

Read-only passthrough of TTS voice catalogs across both supported providers:

* **ElevenLabs** — \~3,000 voices (premade + community)
* **MiniMax** — \~300 system voices spanning Chinese, English, Japanese, and other languages

Cached server-side for 5 minutes per provider so back-to-back calls share one upstream request. Use this to populate a voice picker UI, then pass the chosen `voice_id` to [`POST /v1/audio/speech`](/api-reference/audio-speech).

> **Voice ↔ model compatibility:** ElevenLabs `voice_id`s only work with `eleven-*` SKUs. MiniMax `voice_id`s only work with `minimax-speech-*` SKUs. The two are not cross-compatible.

```bash theme={null}
# Default — ElevenLabs only (back-compat)
curl https://kymaapi.com/v1/audio/voices \
  -H "Authorization: Bearer $KYMA_API_KEY"

# MiniMax system voices
curl "https://kymaapi.com/v1/audio/voices?provider=minimax" \
  -H "Authorization: Bearer $KYMA_API_KEY"

# Both providers merged
curl "https://kymaapi.com/v1/audio/voices?provider=all" \
  -H "Authorization: Bearer $KYMA_API_KEY"
```

## Query parameters

| Param      | Values                             | Default      | Notes                   |
| ---------- | ---------------------------------- | ------------ | ----------------------- |
| `provider` | `elevenlabs` \| `minimax` \| `all` | `elevenlabs` | Which catalog to return |

## Response

`200 OK`. Each voice record carries a `provider` field so you can disambiguate when fetching `?provider=all`.

```json theme={null}
{
  "object": "list",
  "provider": "all",
  "data": [
    {
      "provider": "elevenlabs",
      "voice_id": "JBFqnCBsd6RMkjVDRZzb",
      "name": "George - Warm, Captivating Storyteller",
      "category": "premade",
      "labels": { "accent": "british", "age": "middle_aged", "gender": "male" },
      "preview_url": "https://...",
      "description": "Mature, calm, warm — ideal for narration"
    },
    {
      "provider": "minimax",
      "voice_id": "English_radiant_girl",
      "name": "Radiant Girl",
      "description": ["Energetic", "English", "Female"]
    }
  ]
}
```

### Common fields

| Field      | Type                          | Notes                                  |
| ---------- | ----------------------------- | -------------------------------------- |
| `provider` | `"elevenlabs"` \| `"minimax"` | Which provider serves this voice       |
| `voice_id` | string                        | Opaque id — pass to `/v1/audio/speech` |
| `name`     | string                        | Human-readable name                    |

### ElevenLabs-only fields

| Field         | Type   | Notes                                         |
| ------------- | ------ | --------------------------------------------- |
| `category`    | string | `premade`, `cloned`, etc.                     |
| `labels`      | object | Filter facets — gender, age, accent, use case |
| `preview_url` | string | Short audio sample of the voice               |
| `description` | string | Free-text description                         |

### MiniMax-only fields

| Field         | Type      | Notes                                          |
| ------------- | --------- | ---------------------------------------------- |
| `description` | string\[] | Tags like `["Energetic", "English", "Female"]` |

The full ElevenLabs catalog is large (\~100 KB JSON). For a picker UI, fetch once on mount and cache client-side. The MiniMax catalog is smaller (\~300 voices) and trivial to ship inline.

## Cache headers

| Header                  | What                                                                              |
| ----------------------- | --------------------------------------------------------------------------------- |
| `X-Kyma-Cache: may-hit` | Catalog likely served from Redis (5-min TTL per provider)                         |
| `X-Kyma-Cache: partial` | `?provider=all` — at least one provider returned, possibly cached, possibly fresh |
| `X-Kyma-Cache: miss`    | No Redis available; fetched fresh from upstream                                   |

## Errors

| Status | When                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `provider` query param value is not one of the allowed options                                                                                               |
| `401`  | Missing or invalid API key                                                                                                                                   |
| `502`  | Upstream catalog endpoint unavailable. With `?provider=all`, only returned when **both** providers fail — partial responses succeed with the available data. |

## Picking the right voice for your SKU

| Speech SKU               | Eligible voices                                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `eleven-v3`              | Any `provider: "elevenlabs"` voice                                                                                                            |
| `eleven-multilingual-v2` | Any `provider: "elevenlabs"` voice                                                                                                            |
| `eleven-flash-v2-5`      | Any `provider: "elevenlabs"` voice                                                                                                            |
| `eleven-turbo-v2-5`      | Any `provider: "elevenlabs"` voice                                                                                                            |
| `minimax-speech-hd`      | Any `provider: "minimax"` voice + your own [cloned](/api-reference/audio-voice-clone) or [designed](/api-reference/audio-voice-design) voices |
| `minimax-speech-turbo`   | Any `provider: "minimax"` voice + your own cloned/designed voices                                                                             |

## See also

* [`POST /v1/audio/speech`](/api-reference/audio-speech) — use a `voice_id` from this list
* [`POST /v1/audio/voice-clone`](/api-reference/audio-voice-clone) — create a custom voice from a reference recording (10s–5min)
* [`POST /v1/audio/voice-design`](/api-reference/audio-voice-design) — create a synthesized voice from a text description