Text to speech

Read this text aloud, in this voice. One request, POST /v1/audio/speech, and the audio comes back in the body. Before you start: put a key in EESI_API_KEY — see Authentication — and install a client if you want one, from SDKs. Neither SDK is published to PyPI or npm yet, so both install from a checkout.

curl https://api.eesi.ai/v1/audio/speech \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  -o out.wav \
  -d '{
    "model": "nur-tts-v1",
    "voice": "ev_1a2b3c4d",
    "input": "Your appointment is confirmed for Thursday at two.",
    "response_format": "wav"
  }'

from eesi_sdk import EESIClient
from eesi_sdk.models import SpeechRequest

with EESIClient(api_key="sk-eesi-...") as client:
    # create_speech returns the audio bytes.
    audio = client.create_speech(
        body=SpeechRequest(
            model="nur-tts-v1",
            voice="ev_1a2b3c4d",
            input="Your appointment is confirmed for Thursday at two.",
            response_format="wav",
        )
    )

with open("out.wav", "wb") as f:
    f.write(audio)

import { writeFile } from "node:fs/promises";
import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({ apiKey: process.env.EESI_API_KEY });

const audio = await client.createSpeech({
  body: {
    model: "nur-tts-v1",
    voice: "ev_1a2b3c4d",
    input: "Your appointment is confirmed for Thursday at two.",
    response_format: "wav",
  },
});

await writeFile("out.wav", audio);

ev_1a2b3c4d stands for a real voice id. Get one from GET /v1/voices — built-in and cloned voices both look like this.

The request

Field	Required	Notes
`model`	Yes	A `tts` id from `GET /v1/audio/models`. `nur-tts-v1` today.
`input`	Yes	The text to speak. 1 to 4,096 characters, enforced by the schema — 4,097 is refused before anything is synthesized.
`voice`	Yes	A `voice_id` from your library (`ev_…`), or an OpenAI voice name, which resolves to the model’s own default rather than to that OpenAI voice.
`response_format`	No	`mp3` (default), `wav` or `pcm` for `nur-tts-v1`.
`speed`	No	`0.25` to `4.0`. Default `1.0`.
`stream_format`	No	`audio` (default) or `sse`. Use `sse` with `response_format: "pcm"` for incremental synthesis.
`instructions`	No	A voice-design description, read only when `voice` does not name a stored voice.
`language`	No	Synthesis language, a name or an ISO code. An EESI extension.
`normalize_text`	No	Read numbers, dates and abbreviations in spoken form. An EESI extension.
`source`	No	Free-form label for where the request came from, up to 64 characters. It is recorded on the history entry. The console sends `"playground"`.

`response_format` is not a transcode

The schema accepts OpenAI’s six values, and a model serves only the ones it advertises. nur-tts-v1 advertises mp3, wav and pcm, so asking it for opus, aac or flac is a 400 naming the formats it does serve — not a conversion:

{
  "error": {
    "message": "Model `nur-tts-v1` does not support response_format 'opus'. Supported: mp3, pcm, wav.",
    "type": "invalid_request_error",
    "param": "response_format"
  }
}

Read formats from GET /v1/audio/models rather than trusting the enum. If you need opus, transcode the wav yourself.

A wrong `voice` is refused, not ignored

The synthesis model conditions the speaker on reference audio, not on the string in voice. A name it does not recognize used to be dropped upstream, and the utterance came back in the default voice with a 200 — the hardest failure on this route to diagnose, because nothing said anything was wrong. So the gateway checks the name first. voice must be a voice id (ev_…), an OpenAI voice name, or auto for the model’s own default, and anything else is a 400 unknown_voice before synthesis starts. Passing a voice’s display name (“Nur”) rather than its id lands here. That gate checks the shape of the name, not your library. An ev_… string passes on its prefix alone, and the id is looked up later, when the reference clip is fetched. A typo therefore lands a different error: ev_deadbeef comes back as a 400 whose message is “Unknown voice” and the id you sent, and whose code is null. Two gates, two 400s — do not expect unknown_voice to cover both.

An OpenAI voice name such as alloy does not give you OpenAI’s alloy. It maps to auto, the serving model’s default speaker. Name a voice_id when you care which voice you get.

Incremental speech

For nur-tts-v1, combine response_format: "pcm" with stream_format: "sse" to receive audio as phrases are synthesized. Each speech.audio.delta carries base64 PCM16 audio: signed little-endian, 24 kHz, mono. Play consecutive deltas in order; speech.audio.done closes the stream. Closing the connection cancels remaining synthesis. MP3, WAV and other file formats still finish synthesis before sending the encoded file. Using SSE with those formats changes framing only. The default stream_format: "audio" returns raw response bytes for file download. Short requests reduce the amount of work before playback. Phrase streaming also lets playback begin before a longer request finishes, but reference-voice preparation and synthesis still affect first-audio latency. See Latency.

import httpx

with httpx.stream(
    "POST",
    "https://api.eesi.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "nur-tts-v1",
        "voice": "ev_1a2b3c4d",
        "input": text,
        "response_format": "pcm",
    },
    timeout=120,
) as response:
    response.raise_for_status()
    for chunk in response.iter_bytes():
        play(chunk)

Narrating something long

The 4,096-character cap is per request, so a chapter is several requests. Split on sentence boundaries, synthesize each piece, and concatenate the results. The voice holds across the seam because it is not resampled per request: a voice_id resolves to the same stored reference clip every time, so segment nine sounds like segment one. That is the whole reason voices are a resource rather than a string. Two things to keep straight when you split:

Split at punctuation, not at 4,096 characters. A piece that starts mid-clause is read with the wrong intonation, and no amount of stitching hides it.
Keep speed, voice, language and normalize_text identical across the pieces. Changing any of them mid-document is audible.

There is a worked version of this in Stream speech to a file.

What comes back with the audio

Two headers are worth reading. One is on every response; the other is on every response that produced a history row.

Header	What it is
`X-Synthetic-Audio`	The machine-readable marker declaring the audio as model output. It is also written into the container for `wav` and `mp3`. You cannot turn it off. See Synthetic audio marking.
`X-EESI-Generation-Id`	The id of the history entry this request created. Absent when there is no entry — a deployment with retention turned off, or a row that failed to write. Serving never waits on history, so the audio arrives either way. Exposed to browsers through CORS, so a web client can tie the bytes it received to the row describing them.

Read the header rather than assuming it. A client that indexes by generation id needs a path for the response that has none.

What a generation leaves behind

Where retention is on, each request leaves an entry, so a take you liked can be replayed and downloaded rather than regenerated from memory.

curl "https://api.eesi.ai/v1/generations?limit=20&search=appointment" \
  -H "Authorization: Bearer $EESI_API_KEY"

# The audio, as a short-lived signed URL rather than bytes.
curl "https://api.eesi.ai/v1/generations/$GENERATION_ID/audio" \
  -H "Authorization: Bearer $EESI_API_KEY"

# Removes the entry and erases the stored audio.
curl -X DELETE "https://api.eesi.ai/v1/generations/$GENERATION_ID" \
  -H "Authorization: Bearer $EESI_API_KEY"

with EESIClient(api_key="sk-eesi-...") as client:
    history = client.list_generations(limit=20, search="appointment")
    for entry in history.data:
        print(entry.generation_id, entry.voice_name, entry.duration_seconds)

const history = await client.listGenerations({ limit: 20, search: "appointment" });
for (const entry of history.data) {
  console.log(entry.generation_id, entry.voice_name, entry.duration_seconds);
}

The entry is written before the audio is uploaded, so has_audio is false for a moment after a request finishes, and stays false when the deployment keeps no audio or the upload failed. The row is still a true record of what was said, so it is listed either way. voice_name is denormalized onto the row, which is what keeps history readable after a voice is renamed or deleted. Two caps apply to what the row holds, and both are flagged rather than silent:

input is stored to 4,000 characters. An input near the 4,096-character request cap comes back with text_truncated: true, and character_count still counts what you sent.
Audio is stored to 25 MB. You receive every byte; the stored copy is cut, and the row says audio_truncated: true. A short stored clip is never a short generation.

Fetching the audio needs the generation id and your key: ids appear in storage keys, so holding one is never on its own enough to read the audio.

Cost, limits and failures


Price	$0.001 per minute of generated audio, billed on the duration that comes back rather than on characters sent.
Request rate	60 requests per minute per organization.
Input	4,096 characters per request.
Free plan	1,200 seconds of synthesis per day, resetting at 00:00 UTC. It applies to organizations that have never bought credits; a paying account is bounded by its balance instead.

The failures you will actually meet:

Status	`code`	What happened
400	`unknown_voice`	`voice` is blank, or a string that is neither a voice id, an OpenAI name nor the model’s default. Usually a display name instead of a `voice_id`.
400	—	`voice` is a well-formed `ev_…` id your organization has no voice for, or names a cloned voice whose `status` is not yet `ready`, or names a model that does not support cloned voices.
400	—	`response_format` is a value this model does not serve.
400	`model_wrong_kind`	You posted an `stt` id here. The message names the endpoint that serves it.
400	`string_too_long`	`input` is over 4,096 characters. Schema failures on `/v1/audio/` and `/v1/voices/` come back as a 400 in the OpenAI envelope rather than a 422, with Pydantic’s reason in `code` so a client can branch on it.
404	`model_not_found`	No catalog entry has that id or alias. Read `GET /v1/audio/models`.
429	`rate_limit_exceeded`	Over 60 requests a minute. Slow down and retry.
429	`free_tier_daily_limit`	The free plan’s daily ceiling. It resets at 00:00 UTC, or add credits.
429	`insufficient_quota`	The prepaid balance is empty.
502	`upstream_unreachable`	The serving backend did not answer. Retry with backoff.
502	`upstream_auth_misconfigured`	The gateway’s own credentials were refused upstream. Never your key — report it.
503	`model_unavailable`	A real `tts` id with no backend wired up in this deployment. Pick a served id.
503	—	The backend answered 503 itself: it is up and at capacity. Retry with backoff.

An unreachable backend is a 502, not a 503. Every 502 on this route means the gateway could not get a usable answer out of the model server, and none of them is caused by your request — including the redirect the gateway refuses to follow, upstream_redirect_refused. Branch on the status, then on code. A request that fails one of the gates above is refused before any audio is generated, so it costs nothing. A request that is cut off mid-stream is billed for the audio that was produced, because the GPU pass was already spent. The whole utterance is generated before the first byte, so a long paragraph under load can outlast an SDK’s default budget and raise RequestTimeoutError. In Python that budget is the 60-second read timeout: raise it with EESIClient(timeout=180), where a float covers every phase. In TypeScript the binding default is connectTimeoutMs, ten seconds to response headers — and no headers are sent until the audio exists — so raising readTimeoutMs alone changes nothing. Pass new EESIClient({ connectTimeoutMs: 180_000, readTimeoutMs: 180_000 }), or split the text. Nothing is retried automatically for you: a POST that failed on the wire may still have reached the server.

Voices

Why a voice is a resource, and how to get a voice_id.

Story

A script with a cast, rendered block by block through this endpoint.

Stream speech to a file

Narrate something long without holding it in memory.

Synthetic audio marking

What every response declares about itself.

Authentication

Where an sk-eesi-… key comes from, and what a bad one looks like.

Start here

Realtime interaction

Speech

Platform

The request

`response_format` is not a transcode

A wrong `voice` is refused, not ignored

Incremental speech

Narrating something long

What comes back with the audio

What a generation leaves behind

Cost, limits and failures

Next

Voices

Story

Stream speech to a file

Synthetic audio marking

Authentication

​The request

​response_format is not a transcode

​A wrong voice is refused, not ignored

​Incremental speech

​Narrating something long

​What comes back with the audio

​What a generation leaves behind

​Cost, limits and failures

​Next

Voices

Story

Stream speech to a file

Synthetic audio marking

Authentication

The request

`response_format` is not a transcode

A wrong `voice` is refused, not ignored

Incremental speech

Narrating something long

What comes back with the audio

What a generation leaves behind

Cost, limits and failures

Next