Stream speech to a file

POST /v1/audio/speech returns the whole take when it is done. For long text that means waiting for the last word before you have the first byte — and holding the entire file in memory while you wait. Stream it instead: write each chunk as it arrives.

Prerequisites

An API key

Create one in Settings → API keys, or see Get your API key. Keep it server-side — a key grants full access to your organization.

A voice id

Any voice_id from GET /v1/voices. Built-in voices work; so does one you cloned.

Recipe

import httpx

VOICE = "ev_abc123"
TEXT = open("chapter-one.txt").read()

with httpx.stream(
    "POST",
    "https://api.eesi.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {EESI_API_KEY}"},
    json={
        "model": "nur-tts-v1",
        "voice": VOICE,
        "input": TEXT,
        "response_format": "mp3",
    },
    timeout=None,
) as response:
    response.raise_for_status()
    with open("chapter-one.mp3", "wb") as out:
        for chunk in response.iter_bytes():
            out.write(chunk)

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const response = await fetch("https://api.eesi.ai/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EESI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "nur-tts-v1",
    voice: "ev_abc123",
    input: text,
    response_format: "mp3",
  }),
});

if (!response.ok) throw new Error(await response.text());
await pipeline(Readable.fromWeb(response.body), createWriteStream("chapter-one.mp3"));

curl https://api.eesi.ai/v1/audio/speech \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  -o chapter-one.mp3 \
  -d '{
    "model": "nur-tts-v1",
    "voice": "ev_abc123",
    "input": "…",
    "response_format": "mp3"
  }'

timeout=None matters. A long chapter can take longer than a default client timeout, and the request will be cut mid-synthesis — you will have paid for audio you did not keep.

Text longer than one request

A single request takes up to 4,000 characters. Split on sentence boundaries, not mid-word, and concatenate the parts. The voice does not drift between them. Every voice resolves to the same stored reference clip on every request, so part twelve sounds like part one — see Voices.

import re

def sentences(text: str, limit: int = 3_500) -> list[str]:
    """Group sentences into chunks under the per-request character limit."""
    parts, current = [], ""
    for sentence in re.split(r"(?<=[.!?])\s+", text):
        if len(current) + len(sentence) + 1 > limit:
            parts.append(current.strip())
            current = ""
        current += sentence + " "
    if current.strip():
        parts.append(current.strip())
    return parts

Concatenate the decoded audio, not the encoded files. Joining two MP3s byte-wise produces a stream most players will play and some will not, and the seam is audible. Decode each part, join the samples, encode once.

Server-sent events instead

Set stream_format: "sse" to receive the same audio as server-sent events rather than raw bytes. Reach for it when the audio shares a connection with other messages; for writing a file, raw bytes are less work.

Build

Cookbook

Billing

Stream speech to a file

Prerequisites

Recipe

Text longer than one request

Server-sent events instead

Going further

Text to speech

Voices

​Prerequisites

​Recipe

​Text longer than one request

​Server-sent events instead

​Going further

Text to speech

Voices

Prerequisites

Recipe

Text longer than one request

Server-sent events instead

Going further