Speech: text to speech and speech to text
Speech turns text into natural audio and recordings into text, from one API with your project key. Use it for read-aloud buttons, spoken feedback, pronunciation practice, voice notes and transcribing recorded answers. Yoruba, Hausa and Igbo are handled by voices and transcription made for them.
Speech needs prepaid credit. It costs ₦120 per 1,000 characters spoken and ₦20 per minute transcribed (see Pricing). The same text spoken again with the same voice comes from our cache and is free, so a read-aloud button that thousands of learners press is paid for once.
Text to speech
curl -X POST https://api.appsocom.dev/speech/tts \
-H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Good morning, class. Today we look at fractions.","language":"en"}' \
--output lesson.mp3| Field | |
|---|---|
text |
Up to 5,000 characters. Split longer text into paragraphs. |
language |
en by default. yo, ha and ig for Yoruba, Hausa and Igbo; most major languages work. |
voice |
A voice id. Leave it out for a natural default voice in that language. |
format |
mp3 (default) or wav. |
speed |
0.5 to 2. |
response |
audio (default): the audio file. url: a signed link instead, see below. |
expiresIn |
With response: "url": how long the link works, 60 seconds to 7 days (default one hour). |
cache |
false to always make the audio fresh (always charged). |
The answer's headers say what happened: X-Speech-Cached (true when it came from the cache), X-Speech-Characters (characters charged) and X-Speech-Voice.
A link for browsers and phones
Your API key must stay on your server. To play audio in a browser or app, ask for a link instead and give that to the page:
const { url } = await kit.textToSpeechUrl({ text: paragraph, language: "yo", expiresIn: 3600 });
// <audio src={url} controls />The link plays without your key until it expires, and supports seeking.
Speech to text
Send a recording as the request body (up to 25 MB; mp3, wav, webm, ogg, m4a and most video files work):
curl -X POST "https://api.appsocom.dev/speech/stt?language=en" \
-H "Authorization: Bearer $APPSOCOM_API_KEY" \
-H "Content-Type: audio/webm" \
--data-binary @answer.webm{ "text": "A fraction is part of a whole.", "language": "en", "seconds": 4, "provider": "deepgram",
"words": [{ "word": "A", "start": 0.08, "end": 0.2 }] }Leave language out to detect it (not for Yoruba, Hausa or Igbo: name those). Multipart uploads with a file field work too. seconds is the length charged, rounded up to the next second.
From your server
Node (@appsocom/node):
const audio = await kit.textToSpeech({ text: "Well done!", language: "en" }); // ArrayBuffer (mp3)
const { text } = await kit.speechToText(recording, { contentType: "audio/webm", language: "ha" });Go (github.com/appsotechltd/appsocom-go/sfukit):
audio, err := kit.TextToSpeech(ctx, sfukit.TextToSpeechRequest{Text: "Well done!", Language: "en"})
out, err := kit.SpeechToText(ctx, file, sfukit.SpeechToTextOptions{ContentType: "audio/webm", Language: "ig"})Limits and spending
- Each project has a daily cap on speech spending, $5 a day by default. When it is reached, new audio and transcriptions answer
429until midnight UTC; audio already in the cache still plays. Set a lower cap withPUT /speech/config{"dailyBudgetUsd": 2}. GET /speech/usageshows each day's spending. Monthly usage and charges are in the console with your other usage.- Speech is off on the free plan and when a project runs out of credit (
403).
Who handles the audio
Text to speech uses Cartesia, and Spitch or ElevenLabs for Yoruba, Hausa and Igbo; speech to text uses Deepgram, and Spitch or ElevenLabs for those three languages. Text and recordings are sent to that provider only to make the audio or transcript. Spoken audio is kept in our storage so repeats are free; recordings sent for transcription are not kept. See the DPA.
On Private Cloud, Speech uses your own provider keys on your own Cloudflare account.