Voices API

GET /voices is the single source of truth for which voices your key can speak with and what each call costs. Build your voice picker from this endpoint rather than hardcoding a list — it reflects platform availability, your workspace's cloned voices, and every voice the platform has published, all at once.

Base URL https://platform.oogam.ai/v1 · needs the naad product on your key · read-only, never billed.

Request

A plain authenticated GET — no query parameters. The response is a JSON object with two arrays: voices and models.

bash

curl https://platform.oogam.ai/v1/voices \
  -H "Authorization: Bearer $OOGAM_API_KEY"

json

{
  "object": "list",
  "voices": [
    {
      "voice_id": "aditi",
      "name": "Aditi",
      "language": "Hindi",
      "language_code": "HIN",
      "gender": "female",
      "style": "Warm, conversational",
      "preview": "https://cdn.oogam.ai/voices/aditi.mp3",
      "type": "preset",
      "kind": "builtin",
      "available": true
    },
    {
      "voice_id": "arjun",
      "name": "Arjun",
      "language": "Hindi",
      "language_code": "HIN",
      "gender": "male",
      "style": "Clear, professional",
      "preview": "https://cdn.oogam.ai/voices/arjun.mp3",
      "type": "preset",
      "kind": "builtin",
      "available": false,
      "unavailable_reason": "disabled_by_platform"
    },
    {
      "voice_id": "cmr…9f2a",
      "name": "Support Desk (clone)",
      "language": "GUJ",
      "gender": "female",
      "type": "cloned",
      "kind": "clone",
      "available": true,
      "live_voice_id": "v_9f2a",
      "tenant": "org_8h2k…"
    }
  ],
  "models": [
    {
      "id": "naad-tts-v1",
      "name": "Naad TTS v1",
      "kind": "tts",
      "description": "Lifelike text to speech for Indian languages.",
      "paise_per_k_char": 150
    },
    {
      "id": "naad-stt-v1",
      "name": "Naad STT v1",
      "kind": "stt",
      "description": "Transcription with speaker detection.",
      "paise_per_minute": 100
    }
  ]
}

The voices array

Two kinds of entry appear, distinguished by type / kind: built-in presets and cloned voices. Both expose a voice_id you pass to any TTS, batch speech-to-speech, or conversation call.

Preset voice fields

Field	Type	Description
`voice_id`	string	The id to send in a `voice` field, e.g. `aditi`.
`name`	string	Human-friendly display name.
`language`	string	Primary language, human-readable (e.g. `Hindi`).
`language_code`	string	The matching 3-letter code (e.g. `HIN`).
`gender`	string	`female`, `male`, or `neutral`.
`style`	string	Short description of the delivery.
`preview`	string	URL of a sample clip you can play in your UI.
`type`	string	Always `preset` here.
`kind`	string	Always `builtin` here.
`available`	boolean	Whether your account may use it right now — see below.
`unavailable_reason`	string	Present only when `available` is `false`; e.g. `disabled_by_platform`.

Cloned voice fields

Clones you own and voices the platform has published both appear here, so you can offer branded voices without hardcoding ids.

Field	Type	Description
`voice_id`	string	The id to send in a `voice` field for REST TTS / batch calls.
`name`	string	The clone's name.
`language`	string	Language the clone was trained for (may be `Custom`).
`gender`	string	`female`, `male`, or `neutral`.
`type`	string	Always `cloned` here.
`kind`	string	Always `clone` here.
`available`	boolean	Always `true` for a listed clone (you may use it).
`live_voice_id`	string	Present when the clone can carry a live call — this is the id you pin on the realtime WebSocket via `set_voice`.
`realtime_capable`	boolean	Present as `false` when a clone is batch-only (no `live_voice_id`).
`tenant`	string	Your workspace id — present on clones your workspace owns.
`public`	boolean	`true` when the voice is a platform-published clone (usable by any workspace) rather than your own.

Availability

The available field is why you should drive your UI from this endpoint: a preset can be turned off for your account, and if you send a disabled voice the API returns 400 invalid_voice rather than silently substituting another voice. Grey out or hide any entry where available is false, and surface unavailable_reason if you want to explain why.

Using a voice on the realtime socket

REST audio calls take the voice_id. The realtime WebSocket takes a short live id: presets use f1–f4 / m1–m4, and a cloned voice uses its live_voice_id (a v_… value). If a clone has no live_voice_id (or realtime_capable: false), it is batch-only — use it in TTS but not on a live call. The realtime catalog also has its own discovery endpoints, documented on the realtime page.

The models array

Alongside voices, GET /voices returns the voice model catalogue with current pricing, so your billing display always matches what you are charged.

Field	Type	Description
`id`	string	Model id, e.g. `naad-tts-v1`.
`name`	string	Display name.
`kind`	string	Capability — `tts`, `stt`, `sts`, `s2s`, `isolate`.
`description`	string	One-line summary.
`paise_per_k_char`	number	Present for character-billed models (TTS): paise per 1,000 characters.
`paise_per_minute`	number	Present for minute-billed models (STT, STS, isolation): paise per audio minute.

For the complete model and language catalogue (including the text and embedding models), see Models & languages.