Voices Catalog API

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 — 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

{
  "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
`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

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

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:

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

Saudi voices only (both forms are equivalent):

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"

Genesys TTS Connector

Use the catalog as the Genesys List Voices endpoint

Voice Library

Browse and preview all voices in the dashboard

Getting Started

SDKs

APIs Guides

Agent Guides

Voices Catalog API

Overview

Endpoint

Authentication

Query Parameters

Response

Language Tags

Error Responses

Example Requests

Genesys TTS Connector

Voice Library

​Overview

​Endpoint

​Authentication

​Query Parameters

​Response

​Language Tags

​Error Responses

​Example Requests

​Related

Genesys TTS Connector

Voice Library

Overview

Endpoint

Authentication

Query Parameters

Response

Language Tags

Error Responses

Example Requests

Related