Docs / Products

Text-to-speech

POST /v1/tts turns text into speech with Waridi Sauti. Send JSON, get back audio bytes.

Models

Model Best for Notes
sauti-standard IVR prompts, notifications, high-volume apps Fastest and cheapest. Clear, neutral delivery
sauti-pro Narration, ads, agents, dubbing More expressive prosody and better handling of long sentences

Both models are previews. Latency targets for streaming are on the Streaming page.

Request

from waridi import Waridi

client = Waridi()

audio = client.tts.create(
    model="sauti-pro",
    voice="baraka",
    text="Salio lako ni shilingi elfu kumi na tano. Asante kwa kutumia huduma yetu.",
    language="sw-TZ",
    format="wav",
    sample_rate=24000,
    speed=1.0,
)
audio.save("salio.wav")

import { Waridi } from "@waridi/sdk";
import { writeFile } from "node:fs/promises";

const client = new Waridi();

const audio = await client.tts.create({
  model: "sauti-pro",
  voice: "baraka",
  text: "Salio lako ni shilingi elfu kumi na tano. Asante kwa kutumia huduma yetu.",
  language: "sw-TZ",
  format: "wav",
  sampleRate: 24000,
  speed: 1.0,
});
await writeFile("salio.wav", Buffer.from(await audio.arrayBuffer()));

curl https://api.waridi.io/v1/tts \
  -H "Authorization: Bearer $WARIDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sauti-pro",
    "voice": "baraka",
    "text": "Salio lako ni shilingi elfu kumi na tano. Asante kwa kutumia huduma yetu.",
    "language": "sw-TZ",
    "format": "wav",
    "sample_rate": 24000,
    "speed": 1.0
  }' \
  --output salio.wav

Parameters

Field Type Required Description
model string yes sauti-standard or sauti-pro
voice string yes A preview voice ID such as zawadi, or a cloned voice ID such as vc_01J...
text string yes Up to 5,000 characters. Swahili, English or a mix of both
language string no sw-TZ (default) or sw-KE. Sets pronunciation of numbers, dates and loanwords
format string no mp3 (default), wav, opus or mulaw
sample_rate integer no See the table below. Defaults depend on format
speed number no 0.7 to 1.5. Default 1.0
pronunciations object no Map of word to phonetic spelling, for brand names and place names

Audio formats

format Container Sample rates (Hz) Default Typical use
mp3 MP3, 128 kbps 22050, 24000, 44100 24000 Apps, web playback
wav 16-bit PCM WAV 8000, 16000, 22050, 24000, 44100, 48000 24000 Editing, post-production
opus Ogg Opus 16000, 24000, 48000 24000 Low-bandwidth mobile, WebRTC
mulaw Raw G.711 μ-law 8000 only 8000 Telephony and SIP

For phone lines, use format: "mulaw" with sample_rate: 8000. See Telephony.

Response

A successful request returns 200 OK with the audio as the body and these headers:

Header Example Meaning
Content-Type audio/mpeg Matches format
X-Request-Id req_01J9Z4... Quote this in support requests
X-Audio-Duration-Ms 4120 Length of the generated audio
X-Characters-Billed 78 Characters counted toward usage

Writing text that sounds right

  • Numbers. Write 15,000 or shilingi elfu kumi na tano. With language: "sw-TZ", digits are read in Swahili.
  • Code-switching. Mixed sentences are fine. "Nimekutumia invoice kwenye email yako" keeps invoice and email in natural English.
  • Pauses. A full stop gives a short pause. A new paragraph gives a longer one.
  • Names. Use pronunciations for brand names, for example {"Waridi": "wa-RI-di"}.

Streaming speech

For agents and live apps, generate audio over the WebSocket so playback can start before the full sentence is ready. See Streaming.

PreviousAuthenticationNextSpeech-to-text