Text to Speech voices and options

This page is the lookup table for Text to Speech: what the voices endpoint returns, how to choose a voice, and what each field of a generation request does. It applies to both POST /v1/text-to-speech/sync and POST /v1/text-to-speech, which accept the same body.

Voices endpoint

GET https://api.echonova.ai/v1/text-to-speech/voices

The call takes no parameters. It returns every voice whose status is active, newest first, in one response with no paging. data.total is the count.

{
  "data": {
    "items": [
      {
        "id": "66e5ef3a9c1d2b4f8a7e6c01",
        "name": "ae_ahmed",
        "displayName": "Ahmed",
        "language": "ar",
        "gender": "Male"
      }
    ],
    "total": 1
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}

curl https://api.echonova.ai/v1/text-to-speech/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.echonova.ai/v1/text-to-speech/voices",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
arabic = [v for v in response.json()["data"]["items"] if v["language"] == "ar"]

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/voices', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const { data } = await response.json();
const arabic = data.items.filter((v) => v.language === 'ar');

Choosing a voice

Filter on language in your own code; the endpoint has no filters. ar selects the Arabic voices and en the English ones.

The voice object does not include its dialect. The dialect is fixed by the voice: you send voiceId and nothing else, and the audio comes out in that voice's dialect. To see which dialect a voice speaks, open Voices in the portal. Each card shows the voice's display name and its dialect. Match the card to the API by displayName, or by name when no display name is set, and use that voice's id in your request.

The dialects are egyptian, emirati, saudi, kuwaiti, qatari, omani, lebanese, syrian, iraqi, fusha, american, british and the legacy english. Which of them have voices at a given time can change; the voices call is the source of truth. English voices report language en whatever their dialect.

The set of voices is not fixed. A voice can be withdrawn: it drops out of the list, and a request that names it gets 404 Voice not found. Cache the list for convenience, but refresh it when that error appears.

Choose a voice once and keep its id in configuration, with a path back to the list when the id stops working.

Recommended

• Fetch the list at start-up, pick by displayName and language, keep the id in your configuration, and refetch on 404 Voice not found.

Less effective

• Call GET /v1/text-to-speech/voices before every generation and take the first Arabic voice, whichever it is that day.

Request options

Both generation endpoints take a JSON body with these fields. Leading and trailing whitespace is trimmed from every string before validation. Unknown fields are rejected.

An omitted speed, cfg or numSteps means "use the default", and the job records the value that was used.

About tashkeel

• tashkeel applies to Fusha voices only. On a voice of any other dialect the text is synthesised as written, without diacritics, and the call still succeeds.
• tashkeel takes effect on POST /v1/text-to-speech/sync only. POST /v1/text-to-speech accepts the field and synthesises the text as written. To get diacritised speech, use the synchronous endpoint.
• text on the job is the text you sent; the diacritised text is not returned.

Example with every option

curl -X POST https://api.echonova.ai/v1/text-to-speech/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الطقس اليوم جميل والسماء صافية في المدينة",
    "voiceId": "VOICE_ID",
    "speed": 1,
    "cfg": 2,
    "numSteps": 48,
    "tashkeel": true
  }'

import requests

response = requests.post(
    "https://api.echonova.ai/v1/text-to-speech/sync",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "text": "الطقس اليوم جميل والسماء صافية في المدينة",
        "voiceId": "VOICE_ID",
        "speed": 1,
        "cfg": 2,
        "numSteps": 48,
        "tashkeel": True,
    },
)
print(response.json())

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/sync', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'الطقس اليوم جميل والسماء صافية في المدينة',
    voiceId: 'VOICE_ID',
    speed: 1,
    cfg: 2,
    numSteps: 48,
    tashkeel: true,
  }),
});
console.log(await response.json());

Output

Both endpoints produce one audio file per call and expose it as audioUrl: in the synchronous response directly, and on the job object once the asynchronous job is completed.

Credits

A call is priced from the text field before the job starts: every character of text, spaces and line breaks included, at 1 credit per character. The workspace balance is charged before generation and refunded if the job fails. Rates, worked examples and the credit limit per key are on Credits.

Limits

The two endpoints share one text limit. The difference between them is how you receive the result, not how much text they take.

Errors

Every error uses the standard envelope with success: false and the message in errorMessage. Validation failures list every failing rule in one message, separated by commas.

Authentication failures, 401 and the other 403, are listed on Authentication. The request rate 429 is on Rate limits.

FAQ

How do I know which dialect a voice speaks?

Open Voices in the portal; each card shows the dialect. The API voice object carries language only.

Why does tashkeel do nothing on my job?

Either the voice is not Fusha, or you used POST /v1/text-to-speech. Diacritics are added on POST /v1/text-to-speech/sync with a Fusha voice.

Can I preview a voice through the API?

No. previewUrl is absent from the response. Preview voices in the portal under Voices, or generate a short sentence with POST /v1/text-to-speech/sync.

What do cfg and numSteps change?

Both tune the synthesis. Leave them at their defaults unless you are comparing outputs in your own listening tests; the accepted values are in the table above, and anything outside them is rejected with 400.

Can I get MP3 or OGG?

No. The audio is WAV. Convert it on your side if you need another format.

Related

• Generate speech synchronously
• Generate speech from text
• List available voices
• Text to Speech quickstart
• Credits
• Errors
• Developer API overview