Synthesize
Generate speech from Arabic text and receive a complete WAV audio file. The entire audio is generated before being returned, ensuring complete audio quality.
Endpoint
Requires API key authentication via the x-api-key header. Get a model_id from Models and a voice_id from Voices.
Request
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model_id | string | Yes | The model identifier to use for generation |
Request body — Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
voice_id | string | Yes | The voice ID to use for synthesis |
text | string | Yes | The Arabic text to convert to speech |
stability | number | Yes | Voice stability (0.0 to 1.0). Higher values produce more consistent output |
speed | number | No | Speech speed (0.7 to 1.2, default 1.0). Values below 1.0 slow down speech, above 1.0 speed it up |
streaming | boolean | No | Omit or set false (default) for a complete WAV file response. Set true to receive PCM16 chunks as they're generated — see Audio streaming output. |
sample_rate | number | No | Output sample rate in Hz, 8000–48000 (default 24000). Use 48000 — it's the engine's native rate, so the audio skips downsampling and needs no client-side resampling for WebRTC. |
dialect | string | No | Dialect hint for synthesis: auto (default), emirati, or fusha. |
Pauses
Insert a silence of a fixed length anywhere in text with a break tag. To change the tone of the speech instead, see Emotions. It works on every text-to-speech endpoint, including streaming and word timestamps.
| Property | Value |
|---|---|
| Syntax | <break time="<duration>"/> |
| Units | Required. Seconds (3s, 1.5s) or milliseconds (500ms) |
| Max per tag | 3s — longer values are clamped down to 3 s |
| Max per request | 20 break tags, and about 30 s of pause in total |
| Placement | Anywhere in the text, repeated as needed, within the limits above |
<break time="3"/> produces no pause, no error, and is not spoken — the request succeeds and the tag simply disappears. Always write 3s or 500ms.Every one of these limits degrades quietly rather than returning an error. A 10s tag yields roughly 3 s of silence; past 20 tags or about 30 s of accumulated pause, further breaks add little or nothing. Nothing in the response tells you a limit was hit, so treat the numbers above as a budget you stay inside rather than something the API will enforce for you.
The pause is rendered by the model as part of the audio, so it lands inside the returned waveform and counts toward the clip's duration.
text. There are no separate pause fields on the speakers array.
Emotions
Set the emotion of the speech with an inline tag in text. A tag applies to everything after it until the next tag, so one request can move through several emotions. Tags are never spoken, do not count toward the cost, and work on every text-to-speech endpoint, including streaming, word timestamps and multi-speaker speakers segments.
| Property | Value |
|---|---|
| Syntax | [<emotion>] — square brackets, lowercase, placed before the text it applies to |
| Emotions | excited · happy · calm · serious · sad · fearful · angry |
| Reset | [neutral] ends the current emotion; the text after it is read in the voice's default tone |
| Scope | From the tag to the next tag or the end of the text. Text before the first tag is neutral |
| Placement | Anywhere in the text, repeated as needed. Combine freely with break tags |
When the emotion changes mid-text, each run is generated separately and the audio is joined into one response under one charge. The join is seamless in the waveform, but the engine starts each run fresh, so put tags at natural boundaries — the start of a sentence or clause — rather than in the middle of a phrase.
[angry!] or [joyful], is not an emotion tag: it is passed through as ordinary text and read aloud. Spelling and case are forgiving ([ Happy ] works), but the name must match the list.alignment. Strip the tags from your own string before matching character offsets.
Example request
Leave streaming unset (or false) and save the response body as a WAV file. For chunked output, see Audio streaming output.
Response
Status code: 200 OK. The body is a complete WAV audio file.
| Header | Value |
|---|---|
Content-Type | audio/wav |
Cache-Control | no-cache |
Content-Length | <file_size> |
Error responses
Errors come back as JSON with an errorCode and errorMessage.
| Status | Error code | Example message |
|---|---|---|
| 400 Bad Request | 400xx | Model not found: invalid_model_id |
| 402 Payment Required | 402xx | Insufficient wallet balance. Required: $0.05, Available: $0.02 |
Cost calculation
The cost is calculated from the text length (number of characters) and the model cost per character. Cost is deducted from your wallet balance upon successful generation.
Go further
Working with an AI assistant? Every page is available as Markdown: add .md to the URL, or send an Accept: text/markdown header. For the whole documentation in one request, point it at llms-full.txt; the page index is llms.txt. Or use Copy Page, top right.