Quickstart

curl https://api.eesi.ai/v1/audio/models \
  -H "Authorization: Bearer $EESI_API_KEY"

from eesi_sdk import EESIClient

with EESIClient(api_key="sk-eesi-...") as client:
    for model in client.list_speech_models().data:
        print(model.id, model.kind, model.formats)

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

const client = new EESIClient({ apiKey: process.env.EESI_API_KEY });
const { data } = await client.listSpeechModels();
for (const model of data) console.log(model.id, model.kind, model.formats);

curl https://api.eesi.ai/v1/audio/speech \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  --output hello.wav \
  -d '{
    "model": "nur-tts-v1",
    "voice": "alloy",
    "input": "What is the hardest part of holding a conversation?",
    "response_format": "wav"
  }'

from eesi_sdk import EESIClient
from eesi_sdk.models import SpeechRequest

with EESIClient(api_key="sk-eesi-...") as client:
    audio = client.create_speech(
        body=SpeechRequest(
            model="nur-tts-v1",
            voice="alloy",
            input="What is the hardest part of holding a conversation?",
            response_format="wav",
        )
    )

with open("hello.wav", "wb") as out:
    out.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: "alloy",
    input: "What is the hardest part of holding a conversation?",
    response_format: "wav",
  },
});

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

curl https://api.eesi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -F file=@hello.wav \
  -F model=nur-stt-v1

from eesi_sdk import EESIClient

with EESIClient(api_key="sk-eesi-...") as client, open("hello.wav", "rb") as f:
    result = client.create_transcription(
        file=("hello.wav", f.read(), "audio/wav"),
        model="nur-stt-v1",
    )

print(result["text"])

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

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

const result = (await client.createTranscription({
  file: new Blob([await readFile("hello.wav")], { type: "audio/wav" }),
  model: "nur-stt-v1",
})) as { text: string };

console.log(result.text);

# pip install "websockets>=14"
# 14 is where the top-level `connect` became the asyncio client that takes
# `additional_headers`; on 13 and earlier the argument is `extra_headers`.
import asyncio
import base64
import json
import os
import wave

import websockets

URL = "wss://api.eesi.ai/v1/realtime?model=nur-realtime-v1"
RATE = 16_000
CHUNK_MS = 20
FRAMES_PER_CHUNK = RATE * CHUNK_MS // 1000


async def main() -> None:
    source = wave.open("question.wav", "rb")
    assert source.getframerate() == RATE and source.getnchannels() == 1

    async with websockets.connect(
        URL,
        additional_headers={"Authorization": f"Bearer {os.environ['EESI_API_KEY']}"},
    ) as ws:
        await ws.send(
            json.dumps(
                {
                    "type": "session.update",
                    "session": {
                        "type": "realtime",
                        "instructions": "You are warm and brief. Two sentences at most.",
                        # The voice goes here and nowhere else.
                        "audio": {"output": {"voice": "alloy"}},
                    },
                }
            )
        )

        async def speak() -> None:
            while frames := source.readframes(FRAMES_PER_CHUNK):
                await ws.send(
                    json.dumps(
                        {
                            "type": "input_audio_buffer.append",
                            "audio": base64.b64encode(frames).decode(),
                        }
                    )
                )
                await asyncio.sleep(CHUNK_MS / 1000)
            # Half a second of silence, so end-of-turn detection fires. A file
            # that stops mid-breath leaves the server still waiting for you.
            silence = base64.b64encode(b"\x00" * FRAMES_PER_CHUNK * 2).decode()
            for _ in range(25):
                await ws.send(
                    json.dumps({"type": "input_audio_buffer.append", "audio": silence})
                )
                await asyncio.sleep(CHUNK_MS / 1000)

        speaking = asyncio.create_task(speak())
        reply = bytearray()

        async for raw in ws:
            event = json.loads(raw)
            kind = event["type"]
            if kind == "conversation.item.input_audio_transcription.delta":
                # Cumulative: this REPLACES what you had, it does not append.
                print("you:", event["delta"])
            elif kind == "response.output_audio.delta":
                reply += base64.b64decode(event["delta"])
            elif kind == "response.output_audio_transcript.done":
                # One per segment of the reply, not one per turn.
                print("model:", event["transcript"])
            elif kind == "response.done":
                break

        speaking.cancel()

    with wave.open("reply.wav", "wb") as out:
        out.setnchannels(1)
        out.setsampwidth(2)
        out.setframerate(RATE)
        out.writeframes(bytes(reply))


asyncio.run(main())

// Your server mints the credential; the API key never reaches the page.
const { ticket } = await fetch("/api/realtime-ticket", { method: "POST" })
  .then((response) => response.json());

const ws = new WebSocket(
  `wss://api.eesi.ai/v1/realtime?model=nur-realtime-v1&token=${ticket}`,
);

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        instructions: "You are warm and brief. Two sentences at most.",
        audio: { output: { voice: "alloy" } },
      },
    }),
  );
  startMicrophone(ws); // 16 kHz mono PCM16, ~20 ms per frame
};

ws.onmessage = (message) => {
  const event = JSON.parse(message.data);
  if (event.type === "response.output_audio.delta") {
    play(event.delta); // base64 PCM16
  } else if (event.type === "input_audio_buffer.speech_started") {
    stopPlayback(); // barge-in: drop what is queued, do not drain it
  }
};

curl "https://api.eesi.ai/v1/speech/sessions?limit=5" \
  -H "Authorization: Bearer $EESI_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.eesi.ai/v1/speech/sessions",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {os.environ['EESI_API_KEY']}"},
)
for session in response.json()["sessions"]:
    print(session["session_id"], session["model"], session["duration_seconds"])

const response = await fetch(
  "https://api.eesi.ai/v1/speech/sessions?limit=5",
  { headers: { Authorization: `Bearer ${process.env.EESI_API_KEY}` } },
);

const { sessions } = await response.json();
console.log(sessions);