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, Zarmadje, Frenchfr - Output: WAV (default), MP3, Ogg Opus, or JSON with base64 audio
- Counts: the length of the audio returned
Quickstart
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
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
Keep sentences short
Keep sentences short
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 numbers and dates the way people say them
Write numbers and dates the way people say them
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.
Generate once, play many times
Generate once, play many times
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.
Expect small differences between takes
Expect small differences between takes
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.
Tell people the voice is AI
Tell people the voice is AI
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_longbeyond). - No streaming yet: the whole file comes back at once.
- The first request after a quiet spell is slower while the model wakes up.
Related
Read aloud in Hausa
Tutorial
Audio formats
Guide
API reference
POST /v1/speech