SDKs

Both clients are generated from the backend’s own OpenAPI schema, so they cannot drift from the routes. A method exists here when, and only when, the route behind it carries an sdk_expose decorator — and CI regenerates them and fails on a non-empty diff, which is what keeps that true. That also means the SDKs stop where the schema does. Read What the SDKs do not cover before you go looking for a realtime method.

Install

Neither package is on PyPI or npm yet. Install from a checkout of the repository until they are.

pip install -e sdk/python

pnpm --filter @eesi/sdk build
npm install ./sdk/typescript

The TypeScript package ships dist/, so it has to be built before it is installed.

The client

from eesi_sdk import EESIClient

client = EESIClient(
    base_url="https://api.eesi.ai",   # or EESI_API_URL
    api_key="sk-eesi-...",            # or EESI_API_KEY
)

# It is a context manager, which is how the connection pool gets closed.
with EESIClient() as client:
    print([model.id for model in client.list_speech_models().data])

import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({
  baseUrl: "https://api.eesi.ai",     // or EESI_API_URL
  apiKey: process.env.EESI_API_KEY,   // or EESI_API_KEY
});

const { data } = await client.listSpeechModels();
console.log(data.map((model) => model.id));

base_url is the origin without /v1 — the client appends it. Both arguments fall back to EESI_API_URL and EESI_API_KEY, and the URL defaults to https://api.eesi.ai. An unauthenticated client is legal and 401s on almost everything.

list_speech_models() returns .data, not .models. Every list response on these clients is .data.

Making a call

A request body is either its typed model or a plain mapping of the same fields. A mapping is validated against that model before anything is sent, so a misspelled field raises InvalidRequestError naming it rather than failing on the wire.

from eesi_sdk import EESIClient
from eesi_sdk.models import SpeechRequest

with EESIClient() as client:
    audio = client.create_speech(
        body=SpeechRequest(
            model="nur-tts-v1",
            voice="ev_1a2b3c4d",
            input="The rain had not stopped for three days.",
            response_format="mp3",
        )
    )

    # Identical, and identically checked before it is sent:
    audio = client.create_speech(
        body={
            "model": "nur-tts-v1",
            "voice": "ev_1a2b3c4d",
            "input": "The rain had not stopped for three days.",
        }
    )

with open("line.mp3", "wb") as out:
    out.write(audio)

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

const client = new EESIClient();

const body: CreateSpeechBody = {
  model: "nur-tts-v1",
  voice: "ev_1a2b3c4d",
  input: "The rain had not stopped for three days.",
};

await writeFile("line.mp3", await client.createSpeech({ body }));

Import request models from eesi_sdk.models in Python — that module is the public home for them, so regenerating never moves your import. In TypeScript, declare a body away from its call site as the method’s own …Body type (CreateSpeechBody), not as the response model. The response model types the fields the server defaults — response_format, speed — as always present, which is true coming back and wrong going out.

What the SDKs cover

Surface	Python	TypeScript
Model catalog	`list_speech_models`, `voice_design_options`	`listSpeechModels`, `voiceDesignOptions`
Synthesis	`create_speech`	`createSpeech`
Transcription	`create_transcription`	`createTranscription`
Chat completions	`chat_completions`	`chatCompletions`
Voices	`list_voices`, `get_voice`, `create_voice`, `update_voice`, `delete_voice`	`listVoices`, `getVoice`, `createVoice`, `updateVoice`, `deleteVoice`
Generation history	`list_generations`	`listGenerations`
Usage and billing	`get_current_period_usage`, `get_usage_breakdown`, `get_daily_usage_breakdown`, `get_usage_history`, `get_billing_credits`, `get_organization_turn_metrics_summary`	the same names in camelCase
API keys	`get_api_keys`, `archive_api_key`	`getApiKeys`, `archiveApiKey`

Uploads and audio responses are handled for you: create_speech returns the audio bytes, and create_voice and create_transcription take a file. In Python a file is raw bytes, a binary stream, or a (filename, content) / (filename, content, content_type) tuple — pass the tuple form when the server keys off the extension or the media type, which it does for voice references. In TypeScript it is a Blob.

What the SDKs do not cover

This is the part that saves a support ticket.

Realtime, Story, Sessions and Memory have no method

/v1/realtime is a WebSocket, so it is not an OpenAPI operation and cannot be generated. /v1/story/*, /v1/speech/sessions/* and /v1/user/memory/* are ordinary REST routes that carry no sdk_expose decorator today. Call all of them with raw HTTP or a socket — do not go looking for a method name that does not exist.

Streaming paths are batch-only here

SSE transcription (stream=true) and streamed chat completions come back as a stream the generated client does not decode. Use an OpenAI client against the base URL, or read the response yourself. See OpenAI compatibility.

@eesi/realtime is internal, not a package to install

packages/realtime holds the shared TypeScript decoder for the realtime event stream — alias folding, the cumulative-user-delta rule, assistant segment merging — and every EESI client uses it. It is marked "private": true and is consumed source-direct inside this repository, so it is not something to add to your package.json. The rules it implements are documented in Realtime events; the conformance corpus that pins them is spec/realtime/v1/.

Two key actions are session-only by design

Creating a key and un-archiving one refuse an API key, so neither client has a method for them. See Authentication.

Timeouts and retries

Identical in both clients — change one and you change both.

Behaviour	Value
Connect timeout	10 s
Read timeout	60 s
Retry	`GET` once, after a 100–300 ms jittered pause, on a connection failure
Everything else	Never retried

A POST, PUT, PATCH or DELETE that failed on the wire may still have reached the server, and a read timeout means the server took the request — so a retry there is a second voice cloned or a second charge, not a second attempt. Retry those yourself, when you know the operation is safe to repeat. Synthesis of a long input can outrun the 60-second read timeout. Raise it for that call, or stream the response yourself — see Stream speech to a file.

import httpx
from eesi_sdk import EESIClient

client = EESIClient(timeout=httpx.Timeout(connect=10.0, read=300.0, write=300.0, pool=10.0))

import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({ connectTimeoutMs: 10_000, readTimeoutMs: 300_000 });

Errors

Everything raised subclasses EESISdkError, so you can catch the categories separately or together.

Error	Raised when
`ApiError`	Any non-2xx response
`InvalidRequestError` (Python)	A body could not be built — nothing was sent
`RequestTimeoutError`	Connect or read timeout

ApiError reads both envelopes the backend uses — FastAPI’s {"detail": …} from the control-plane routes and OpenAI’s {"error": {…}} from the speech routes — so message is always the server’s own sentence. code and type are set only when the envelope carries them.

from eesi_sdk.errors import ApiError, InvalidRequestError, RequestTimeoutError

try:
    client.get_voice("ev_does_not_exist")
except ApiError as error:
    print(error.status_code, error.code, error.message)
except InvalidRequestError as error:
    print("never sent:", error.errors)
except RequestTimeoutError as error:
    print("timed out:", error)

import { ApiError, RequestTimeoutError } from "@eesi/sdk";

try {
  await client.getVoice("ev_does_not_exist");
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.statusCode, error.code, error.message);
  } else if (error instanceof RequestTimeoutError) {
    console.error("timed out:", error.message);
  } else {
    throw error;
  }
}

The field is status_code in Python and statusCode in TypeScript. Both also carry body — the parsed JSON, or the raw text of a non-JSON response.

Every status and code you will meet is in Errors.

Regenerating

After changing a route or an sdk_expose decorator:

./scripts/generate_sdk.sh

That rebuilds the OpenAPI slice, the request and response models, the client mixins and the reference spec in these docs. CI runs it and fails on a non-empty diff.

Quickstart

A key, a synthesized line, and a live conversation.

OpenAI compatibility

Point an existing OpenAI client here instead.

Errors

The codes behind every ApiError.

Cookbook

Working recipes, end to end.

Build

Cookbook

Billing

Install

The client

Making a call

What the SDKs cover

What the SDKs do not cover

Timeouts and retries

Errors

Regenerating

Next

Quickstart

OpenAI compatibility

Errors

Cookbook

​Install

​The client

​Making a call

​What the SDKs cover

​What the SDKs do not cover

​Timeouts and retries

​Errors

​Regenerating

​Next

Quickstart

OpenAI compatibility

Errors

Cookbook

Install

The client

Making a call

What the SDKs cover

What the SDKs do not cover

Timeouts and retries

Errors

Regenerating

Next