Legacy Text-to-Speech

Legacy

Voice 1 is deprecated

This page preserves the original Voice 1 Base64 and streaming workflow for existing applications. New integrations should use Text-to-Speech with Addis Voices 2.

The legacy Text-to-Speech (TTS) API is powered by our አሌፍ-Audio engine. It is designed to produce human-quality speech for African languages, correctly handling Ge'ez punctuation (like ።, ፣) for natural pausing and intonation.

Usage Guide

The API accepts text and returns a Base64 encoded audio string (WAV format). This allows you to easily embed audio in web apps or save it to disk.

Basic Synthesis

Generate audio from a simple text string.

import AddisAI from "addisai";

const addis = new AddisAI();
const audio = await addis.legacy.audio.generate({
  text: "ሰላም፣ እንኳን ወደ አዲስ ኤአይ በደህና መጡ።",
  language: "am",
});

await audio.toFile("output.wav");

from addisai import AddisAI

addis = AddisAI()
audio = addis.legacy.audio.generate(
    text="ሰላም፣ እንኳን ወደ አዲስ ኤአይ በደህና መጡ።",
    language="am",
)

audio.to_file("output.wav")

curl -X POST https://api.addisassistant.com/api/v1/audio \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: $ADDIS_API_KEY" \\
  -d '{
    "text": "ሰላም፣ እንኳን ወደ አዲስ ኤአይ በደህና መጡ።",
    "language": "am"
  }'

Streaming (Long Text)

Generating audio for long paragraphs takes time. To minimize the wait (latency), use Streaming.

The API will send chunks of audio immediately as they are generated, allowing your app to start playing audio within milliseconds, even if the text is very long.

Usage: Set "stream": true in your request body.

import AddisAI from "addisai";
import { createWriteStream } from "node:fs";

const addis = new AddisAI();
const stream = await addis.legacy.audio.stream({
  text: "ይህ ረጅም ጽሑፍ ነው።",
  language: "am",
});

const output = createWriteStream("output_stream.wav");
for await (const chunk of stream) output.write(chunk);
output.end();

from addisai import AddisAI

addis = AddisAI()
stream = addis.legacy.audio.stream(
    text="ይህ ረጅም ጽሑፍ ነው።",
    language="am",
)

stream.to_file("output_stream.wav")

Best for: Chatbots and Web Apps. This script creates a queue to play chunks smoothly in order.

async function streamAudio() {
  const audioQueue = [];
  let isPlaying = false;

  try {
    const response = await fetch("/api/legacy-audio/stream", {
      method: "POST",
      body: JSON.stringify({
        text: "ይህ ረጅም ጽሑፍ ነው። የአዲስ ኤአይ የድምጽ ቴክኖሎጂ ትልልቅ ጽሑፎችን በቀላሉ አንብቦ ድምጽ ሊያወጣ ይችላል።",
        language: "am",
        stream: true,
      }),
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    // Play audio chunks sequentially
    function playNext() {
      if (audioQueue.length === 0) {
        isPlaying = false;
        return;
      }
      isPlaying = true;
      const nextChunk = audioQueue.shift();
      const audio = new Audio("data:audio/wav;base64," + nextChunk);
      audio.onended = playNext;
      audio.play().catch(e => console.error("Playback failed:", e));
    }

    // Read the stream
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value, { stream: true });
      const lines = chunk.split("\n").filter((line) => line.trim());

      for (const line of lines) {
        try {
          const data = JSON.parse(line);
          if (data.audio_chunk) {
            audioQueue.push(data.audio_chunk);
            if (!isPlaying) playNext();
          }
        } catch (e) {
          console.error("JSON Parse Error:", e);
        }
      }
    }
  } catch (error) {
    console.error("Stream connection failed:", error);
  }
}

streamAudio();

Best for: testing the legacy stream from a terminal.

curl -X POST https://api.addisassistant.com/api/v1/audio \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: $ADDIS_API_KEY" \\
  -d '{
    "text": "ይህ ረጅም ጽሑፍ ነው።",
    "language": "am",
    "stream": true
  }'

API Reference

Request Parameters

These parameters go in the root of your JSON body.

Prop

Type

Response Schema (Basic Mode)

If stream: false, you receive a single JSON object.

{
  "audio": "//NIxAAAAANIAAAAAExBTUVVVV..."
}

Prop

Type

Response Schema (Streaming Mode)

If stream: true, you receive newline-delimited JSON objects.

{"audio_chunk": "//NIxAAAAANIA...", "index": 0}
{"audio_chunk": "AAAEkSRJ...", "index": 1}

Handling the Audio Output

The API returns audio as a Base64 encoded string. This makes it easy to send JSON data, but you cannot play it directly without decoding it.

Audio Tool

Use this tool to test your API output. Paste the audio string from your response to hear it immediately.

Base64 Audio Player

Paste the audio string from your API response here to verify it.

Code Implementation

Here is how to decode and save the audio file programmatically in your application.

Choose your environment:

Universal Command (Windows/Mac/Linux)

You can decode and save the file in one command line using Python (pre-installed on most systems).

curl -X POST https://api.addisassistant.com/api/v1/audio \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADDIS_API_KEY" \
  -d '{"text": "ሰላም", "language": "am"}' \
  | python3 -c "import sys, json, base64; open('output.wav', 'wb').write(base64.b64decode(json.load(sys.stdin)['audio']))"

To save the file to disk in a backend environment:

import fs from 'fs';

// Assuming 'data' is the JSON response from fetch()
const base64String = data.audio;
const buffer = Buffer.from(base64String, 'base64');

fs.writeFileSync('speech.wav', buffer);
console.log('Saved to speech.wav');

To decode and save the file in a Python script:

import base64

# Assuming 'response_json' is the dict from requests.post().json()
base64_string = response_json['audio']
audio_data = base64.b64decode(base64_string)

with open("speech.wav", "wb") as f:
    f.write(audio_data)

print("Saved to speech.wav")

To play the audio immediately in a React or Vue app:

// Assuming 'data' is the JSON response from the API
const base64String = data.audio;

// Create a playable Audio object directly
const audio = new Audio("data:audio/wav;base64," + base64String);
audio.play();

Best Practices

Ensure high-quality voice output with these guidelines.

Script & Punctuation

Use Punctuation: The model relies on commas (፣) and periods (።) to determine pauses. Text without punctuation will sound rushed.

Avoid Mixed Scripts: Mixing English words inside an Amharic sentence may result in unnatural pronunciation. Transliterate English terms into Fidel if possible.

Latency Optimization

Long DocumentsUse stream: true

There is no hard character limit, but generating a large file takes time. For texts longer than 2 sentences, always use Streaming to ensure immediate playback.

Efficiency

Cache Everything: TTS is deterministic. If the input text hasn't changed, serve the saved audio file instead of calling the API again to save money and bandwidth.

Output Format

Base64 WAV: The API returns a Base64 string inside JSON. You must decode this string to get the playable WAV file.

Compression: Since WAV is large and uncompressed, consider converting the decoded audio to MP3 on your backend if your users are on mobile data.

Migrate to Addis Voices 2

Addis Voices 2 adds catalog discovery, previews, estimates, durable clips, idempotency, and minute-based billing. Start with the Addis Voices 2 Text-to-Speech guide, select a current catalog voice such as am-hamen, and migrate one existing use case at a time. The current guide includes a field-by-field migration summary.