Streaming

Play speech as it is generated over HTTP or a persistent WebSocket. Choose a voice and enter your API key to try it live.

Use HTTP for individual requests or WebSockets for successive turns on one connection. For microphone conversations with AI responses, see the Realtime API.

Choose a language and voice

Fetch the current catalog with voices.list({ language: "ti" }) in Node.js or voices.list(language="ti") in Python. Select an available voice whose language matches the request. The examples below use Berhane (ti-berhane, ti); use Hamen (am-hamen, am) or Bikila (om-bikila, om) in the same calls for the other documented languages.

curl --fail-with-body \
  "https://api.addisassistant.com/api/v1/voice/voices?language=ti" \
  -H "x-api-key: $ADDIS_API_KEY"

Send complete sentences. A single word or a few letters can produce poor speech; let the service divide an utterance into phrases.

Stream with the SDK

Install the SDK and set ADDIS_API_KEY on your server.

Persistent WebSocket

Connect once and reuse the connection for successive turns. Wait for each turn to finish before starting another, and save a unique request ID before sending it.

import { createWriteStream } from "node:fs";
import { randomUUID } from "node:crypto";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import AddisAI from "addisai";

const addis = new AddisAI();
const requestId = randomUUID(); // Persist this ID to recover the same turn.
const connection = await addis.realtime.connect({
  voiceId: "ti-berhane",
  language: "ti",
  maxTextCharacters: 1000,
});

try {
  await pipeline(
    Readable.from(connection.speak(
      "ሰላም፣ እንቋዕ ናብ ኣዲስ ኤኣይ ብደሓን መጻእኩም።",
      requestId,
    )),
    createWriteStream("speech.mp3"),
  );
  console.log(connection.lastCompletion?.usage);
} finally {
  connection.close();
}

pip install "addisai[realtime]==0.4.0"

from uuid import uuid4
from addisai import AddisAI

request_id = str(uuid4())  # Persist this ID to recover the same turn.

with AddisAI() as addis:
    with addis.realtime.connect(
        voice_id="ti-berhane", language="ti", max_text_characters=1000,
    ) as connection:
        with open("speech.mp3", "wb") as output:
            for chunk in connection.speak(
                "ሰላም፣ እንቋዕ ናብ ኣዲስ ኤኣይ ብደሓን መጻእኩም።",
                request_id,
            ):
                output.write(chunk)
        print(connection.last_completion["usage"])

The file examples consume the stream completely. For playback during generation, feed the chunks to a streaming MP3 player in their received order. speak() uses an MP3 session.

HTTP streaming

Use HTTP when each utterance is an independent request. The SDK handles the audio framing and final billing metadata.

import AddisAI from "addisai";

const addis = new AddisAI();
const audio = await addis.voice.stream({
  voiceId: "ti-berhane",
  language: "ti",
  text: "ሰላም፣ እንቋዕ ናብ ኣዲስ ኤኣይ ብደሓን መጻእኩም።",
  clientRequestId: "my-persisted-turn-id",
});

await audio.toFile("speech.mp3");
console.log(audio.metadata?.usage);

from addisai import AddisAI

with AddisAI() as addis:
    audio = addis.voice.stream(
        voice_id="ti-berhane", language="ti",
        text="ሰላም፣ እንቋዕ ናብ ኣዲስ ኤኣይ ብደሓን መጻእኩም።",
        client_request_id="my-persisted-turn-id",
    )

    audio.to_file("speech.mp3")
    print(audio.metadata["usage"])

To play audio immediately, iterate audio rather than waiting for the file helper to finish. HTTP streaming accepts mp3_44100; use voice.generate for other formats. Check the format returned in audio events rather than inferring its sample rate from the output format name.

curl --fail-with-body \
  https://api.addisassistant.com/api/v1/realtime/sessions \
  -H "x-api-key: $ADDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "ti-berhane",
    "language": "ti",
    "audio_format": "mp3",
    "max_text_characters": 1000
  }'

async function streamSpeech(text, requestId, onAudio) {
  const response = await fetch("/my-server/voice-session", { method: "POST" });
  if (!response.ok) throw new Error("Could not create a voice session");
  const session = await response.json();
  const socket = new WebSocket(session.websocket_url);

  return new Promise((resolve, reject) => {
    let completed = false;
    socket.onopen = () => {
      socket.send(JSON.stringify({
        type: "session.authenticate", token: session.token,
      }));
    };
    socket.onmessage = ({ data }) => {
      try {
        const event = JSON.parse(data);
        if (event.type === "session.created") {
          socket.send(JSON.stringify({
            type: "speech.create", text, request_id: requestId,
          }));
        } else if (event.type === "audio.delta") {
          const bytes = Uint8Array.from(atob(event.audio), c => c.charCodeAt(0));
          onAudio(bytes, event.format); // Enqueue chunks in the received order.
        } else if (event.type === "speech.completed") {
          completed = true;
          resolve(event.data); // Saved clip, playback URL, and usage.
          socket.close();
        } else if (event.type === "error") {
          throw new Error(`${event.error.code}: ${event.error.message}`);
        }
      } catch (error) {
        reject(error);
        socket.close();
      }
    };
    socket.onerror = () => reject(new Error("Voice connection failed"));
    socket.onclose = () => {
      if (!completed) reject(new Error("Stream ended before billing confirmation"));
    };
  });
}

Billing and recovery

Voice streaming uses the same 5 ETB per generated minute pricing and wallet as Addis Voices 2 clips. Read voice.usage() for current pricing and balance. Billing depends on measured audio duration; a text-based estimate can differ from the final charge.

Consume the stream through speech.completed, or the HTTP completion record, to receive the saved clip and confirmed usage. Audio delivery alone does not confirm settlement. Store the returned clip ID and usage with your application's turn ID.

• Keep request_id / client_request_id stable when retrying the same text, voice, language, and output format. A changed input requires a new ID.
• An HTTP replay returns the previously saved clip; the SDK downloads its audio without another synthesis or charge.
• A WebSocket replay returns speech.completed with idempotent_replay: true and the original clip. It does not stream the audio again; fetch the clip to play it.
• speech.cancel mutes subsequent audio delivery and clears buffered text. A generation already started continues, saves its clip, and is billed. Disconnecting has the same billing behavior.
• If a stream ends before completion, keep the original ID and inputs for recovery rather than issuing a new billable generation.

Streaming limits

There is no fixed cap on sessions or requests per API key. Your wallet balance bounds spending: each session holds credit for one turn and releases what it does not use when it ends. When the voice servers for a language are fully busy, a request returns 429 with LANGUAGE_CAPACITY_REACHED and a Retry-After header (retry_after_seconds on WebSockets). Retry after that delay with the same request ID.

Request IDs accept 1–128 ASCII letters, digits, _, or -. The voice and language are fixed for a session. SDK helpers generate an ID when one is omitted; save your own ID when your application needs to recover a turn after a restart.