Text to speech

POST /v1/audio/speech reads text aloud and returns the audio in the response body. The model is nur-v1.

curl https://api.eesi.ai/v1/audio/speech \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  -o out.mp3 \
  -d '{
    "model": "nur-v1",
    "voice": "ev_d116d96b",
    "input": "Your table is booked for Thursday at eight."
  }'

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["EESI_API_KEY"], base_url="https://api.eesi.ai/v1")

speech = client.audio.speech.create(
    model="nur-v1",
    voice="ev_d116d96b",
    input="Your table is booked for Thursday at eight.",
)
speech.write_to_file("out.mp3")

import { writeFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.EESI_API_KEY, baseURL: "https://api.eesi.ai/v1" });

const speech = await client.audio.speech.create({
  model: "nur-v1",
  voice: "ev_d116d96b",
  input: "Your table is booked for Thursday at eight.",
});
await writeFile("out.mp3", Buffer.from(await speech.arrayBuffer()));

ev_d116d96b is Nur’s voice. List the others with GET /v1/voices, or clone your own.

Parameters

Field	Required	Notes
`model`	Yes	`nur-v1`.
`input`	Yes	The text, up to 30,000 characters (about half an hour of speech).
`voice`	Yes	A voice id such as `ev_d116d96b`. OpenAI names like `alloy` map to the default voice.
`response_format`	No	`mp3` (default), `wav` or `pcm` (16-bit, 24 kHz, mono).
`speed`	No	0.25 to 4.0. Default 1.0.
`language`	No	The language to speak, such as `en`, `ar` or `ja`. Left out, the model reads it from the text.
`normalize_text`	No	`true` reads numbers, dates and currency as words.
`instructions`	No	Describe a voice instead of naming one, such as `"female, low pitch, british accent"`. Used when `voice` is `"auto"`.
`stream_format`	No	`sse` with `response_format: "pcm"` streams audio as it is made.

Languages and accents

Write the text in the language you want. For Arabic, language also picks the dialect’s pronunciation: ar is Modern Standard Arabic, and dialect codes such as arz (Egyptian), ars (Najdi), afb (Gulf), apc (Levantine) and ary (Moroccan) speak with that region’s accent. A cloned voice speaks every language, and keeps a hint of the accent it was recorded in. Record the clip in the language you will use most.

Stream audio as it is made

For low latency, ask for PCM over server-sent events. Each speech.audio.delta event carries base64 PCM (16-bit, 24 kHz, mono) for the next phrase, and speech.audio.done ends the stream.

import base64, json, os

import httpx

with httpx.stream(
    "POST",
    "https://api.eesi.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['EESI_API_KEY']}"},
    json={
        "model": "nur-v1",
        "voice": "ev_d116d96b",
        "input": "This sentence starts playing before the next one is ready.",
        "response_format": "pcm",
        "stream_format": "sse",
    },
    timeout=60,
) as response:
    for line in response.iter_lines():
        if line.startswith("data:"):
            event = json.loads(line[5:])
            if event["type"] == "speech.audio.delta":
                player.write(base64.b64decode(event["audio"]))

Long text

A chapter or an article can go in one request: input takes up to 30,000 characters. Long text takes a few minutes to make, and the file arrives once all of it is made, so give the request a timeout of a few minutes. To hear it as it is made, ask for pcm with stream_format: "sse". Longer than that, split at paragraph or sentence boundaries and request each part with the same voice: every request with a voice id produces the same speaker, so the parts join cleanly.

Errors

Status	Meaning
`400 unknown_voice`	`voice` is not a voice id or a known name. A display name such as `"Nur"` lands here; use the id.
`400`	The voice is still processing, or `response_format` isn’t one of `mp3`, `wav`, `pcm`.
`429`	Rate limit or out of credits.

Every response carries X-Synthetic-Audio, which declares the audio machine-generated.

Get started

Quickstarts

Nur

Speech

Audio intelligence

Text to speech

Parameters

Languages and accents

Stream audio as it is made

Long text

Errors

​Parameters

​Languages and accents

​Stream audio as it is made

​Long text

​Errors

Parameters

Languages and accents

Stream audio as it is made

Long text

Errors