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

# Voices Catalog API

> List the Hamsa TTS voices available to your API key, with BCP-47 language tags — built for TTS connector integrations

## Overview

The Voices Catalog is a read-only endpoint that returns every TTS voice your API key can use: Hamsa's published voice library plus any custom (cloned) voices owned by your account. Each voice carries a standard **BCP-47 language tag** (`ar-SA`, `ar-EG`, `en-US`) instead of Hamsa's internal dialect codes, so third-party platforms — such as the [Genesys TTS Connector](/developers/apis/genesys-tts-connector) — can consume it directly.

The response is deliberately flat (`voices` at the top level, `id` / `name` / `language` / `gender` per voice) to match connector defaults with zero attribute remapping.

***

## Endpoint

```
GET https://api.tryhamsa.com/v2/tts/voices/catalog
```

### Authentication

Send your Hamsa API key in the `Authorization` header:

```
Authorization: Token <your-hamsa-api-key>
```

### Query Parameters

| Parameter  | Type   | Required | Description                                                                                                                                       |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language` | string | No       | Only return voices for this language or dialect. Accepts a BCP-47 tag (`ar-SA`) or an internal dialect code (`ksa`). Omit to get the full catalog |

### Response

```json theme={null}
{
  "voices": [
    {
      "id": "6b52beba-b560-45d4-827b-49be73d50db7",
      "name": "Amjad",
      "language": "ar-SA",
      "gender": "male"
    },
    {
      "id": "4d8bb0fe-0a55-41b4-b367-33ba36dc0f67",
      "name": "Sarah",
      "language": "en-US",
      "gender": "female"
    }
  ]
}
```

| Field      | Type           | Description                                                                                                              |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`       | string (UUID)  | The voice id. Use it as `voiceId` in the [Connector TTS API](/developers/apis/genesys-tts-connector#synthesize-endpoint) |
| `name`     | string         | Human-readable voice name                                                                                                |
| `language` | string         | BCP-47 language tag (see the table below)                                                                                |
| `gender`   | string \| null | `male` or `female`; `null` when not tagged                                                                               |

<Note>
  The list includes your own cloned voices in addition to the public library. Cloned voices are visible only to the account that owns them.
</Note>

### Language Tags

| Dialect                | Tag     |
| ---------------------- | ------- |
| Saudi                  | `ar-SA` |
| Gulf                   | `ar-SA` |
| Egyptian               | `ar-EG` |
| Palestinian            | `ar-PS` |
| Syrian                 | `ar-SY` |
| Iraqi                  | `ar-IQ` |
| Jordanian              | `ar-JO` |
| Lebanese               | `ar-LB` |
| Emirati                | `ar-AE` |
| Bahraini               | `ar-BH` |
| Qatari                 | `ar-QA` |
| Kuwaiti                | `ar-KW` |
| Omani                  | `ar-OM` |
| Modern Standard Arabic | `ar`    |
| English                | `en-US` |

### Error Responses

| Status | Meaning                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | Validation error — `language` must be a non-empty string |
| `401`  | Invalid or missing API key                               |

***

## Example Requests

Full catalog:

```bash theme={null}
curl https://api.tryhamsa.com/v2/tts/voices/catalog \
  -H "Authorization: Token your-hamsa-api-key"
```

Saudi voices only (both forms are equivalent):

```bash theme={null}
curl "https://api.tryhamsa.com/v2/tts/voices/catalog?language=ar-SA" \
  -H "Authorization: Token your-hamsa-api-key"

curl "https://api.tryhamsa.com/v2/tts/voices/catalog?language=ksa" \
  -H "Authorization: Token your-hamsa-api-key"
```

***

## Related

<CardGroup cols={2}>
  <Card title="Genesys TTS Connector" icon="plug" href="/developers/apis/genesys-tts-connector">
    Use the catalog as the Genesys List Voices endpoint
  </Card>

  <Card title="Voice Library" icon="microphone" href="https://media.tryhamsa.com/app/voices">
    Browse and preview all voices in the dashboard
  </Card>
</CardGroup>