# 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](https://docs.appsocom.dev/pricing.md)). 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

```bash
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:

```js
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):

```bash
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
```

```json
{ "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`):

```js
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`):

```go
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 `429` until midnight UTC; audio already in the cache still plays. Set a lower cap with `PUT /speech/config` `{"dailyBudgetUsd": 2}`.
- `GET /speech/usage` shows 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](https://docs.appsocom.dev/dpa.md).

On [Private Cloud](https://docs.appsocom.dev/private-cloud.md), Speech uses your own provider keys on your own Cloudflare account.
