Skip to main content

Overview

POST /v1/speech takes up to 2,000 characters of text and returns the audio, spoken by the voice you choose. Use it to read messages to people who prefer listening to reading: health reminders, farming advice, school lessons, announcements, a reply in a chat app.
  • Model: speech-synthesis (beta)
  • Languages: Hausa ha, Zarma dje, French fr
  • Output: WAV (default), MP3, Ogg Opus, or JSON with base64 audio
  • Counts: the length of the audio returned

Quickstart

“The rainy season has set in. It is time for farmers to start sowing millet and sorghum.”

Request

string
required
What to say, up to 2,000 characters. Write it as you want it heard: spell out abbreviations your listeners would not say.
string
default:"nadia"
nadia (or its alias warm), mouhamad or fr. See voices.
string
ha, dje or fr. Defaults to the voice’s first language; it must be a language the voice speaks.
string
default:"wav"
wav, mp3, opus or json. See output formats.

Voices

Output formats

The binary formats return an X-Audio-Seconds header with the length of the audio. A ten-second sentence is about 480 KB as WAV, 80 KB as MP3 and 40 KB as Opus: on a 3G connection, pick opus or mp3. With json, the answer looks like this:

Best practices

One idea per sentence sounds clearer and is easier to follow on a phone speaker. For a long text, send it paragraph by paragraph and play the pieces one after another: the first one starts playing sooner.
Write “goma sha biyar” rather than “15” when you need a number said a particular way, and spell out dates, prices and abbreviations. You control exactly what is heard.
A reminder sent to a thousand people is the same audio. Generate it once, store the file, and serve it from your own storage: it saves your allowance and loads faster for everyone.
The model says a sentence a little differently each time. If one take matters (an announcement, a jingle), generate two or three and keep the one you prefer.
Let listeners know the voice is generated, especially for health, money or official information. See responsible use.

Limits

  • Up to 2,000 characters per request (413 text_too_long beyond).
  • No streaming yet: the whole file comes back at once.
  • The first request after a quiet spell is slower while the model wakes up.

Read aloud in Hausa

Tutorial

Audio formats

Guide

API reference

POST /v1/speech