---
title: Voices
description: Find the right voice and use its ID in a request.
---

List public voices and your own private voices, then use a returned `id` for speech. Voice metadata requires an [API key](/docs/authentication).

## List voices

```bash
curl --fail --show-error \
  'https://api.sawtakarabi.ai/v1/voices?dialect=saudi-najdi&limit=10' \
  -H "Authorization: Bearer $SAWTAK_API_KEY"
```

| Parameter | Default | Description |
| --- | --- | --- |
| `sort` | `newest` | `newest`, `oldest`, or `most_liked`. |
| `limit` | `25` | Page size, 1–100. |
| `after` | — | `next_cursor` from the previous page. Keep the same filters and sort order. |
| `sharing_status` | — | `public` or `private`. Omit to include public voices and your own. |
| `dialect` | — | Exact dialect code from `labels.dialect`, such as `saudi-najdi`. Repeat to match several codes. |
| `gender` | — | `male`, `female`, or `neutral`. |
| `age` | — | `young`, `middle`, or `old`. |
| `use_case` | — | `conversational`, `narration`, or `advertisement`. |
| `search` | — | Search voice names, up to 256 characters. |

Dialect matching is exact: `eg` does not include `eg-cairene`. The [agent skill](/docs/agent-skill) can look up dialect names.

The response contains `object: "list"`, `data`, `first_id`, `last_id`, and `has_more`. When `has_more` is true, pass `next_cursor` as `after` to get the next page.

## Voice fields

`GET /v1/voices/{id}` returns the same voice object used in `data`:

| Field | Description |
| --- | --- |
| `object` | `"voice"`. |
| `id` | Pass this as `voice` in a speech request. |
| `name` | Display name. |
| `status` | `ready` or `processing`. Choose a ready voice for synthesis. |
| `labels` | `dialect`, `gender`, `age`, and `use_case`. Dialect may be null. |
| `preview_url` | Address of the voice's audio preview. |
| `sharing` | `status` (`public` or `private`) and `liked_by_count`. |
| `created_at` | UTC creation time in `YYYY-MM-DDTHH:mm:ss` format. |
| `description` | Optional description. |
| `preview_text` | Optional preview transcript. |

Unavailable or inaccessible voices return `404 voice_not_found`.

## Preview audio

`GET /v1/voices/{id}/preview` returns WAV audio. Public previews need no key; private previews require the owner's key. A missing sample returns `404`, even if the voice is ready for synthesis.

Previews allow 60 requests/minute per IP. On `429`, follow `Retry-After`.

Use the selected ID with [Text to speech](/docs/text-to-speech). To create or manage a private voice, see [Voice cloning](/docs/voice-cloning).