Voices
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.
List voices
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 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. To create or manage a private voice, see Voice cloning.