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