# Text to Speech with Word Timings

Text to speech (TTS) for narration: natural English voices as MP3, with the start and end time of every word for captions and video.

Send English text and get an MP3 at a steady loudness with the start and end of every word. Up to 2,000 characters are spoken in the same call, usually within a second; up to 20,000 characters are queued and split for you. Pauses are written as <break time="500ms"/>, and say_as fixes names the voice gets wrong. Words the voice cannot pronounce are skipped.

- The start and end of every word comes back with the audio, so captions and video cuts line up.
- Steady loudness from first sentence to last; long text up to 20,000 characters is split for you.
- Pauses with break tags, and say_as for names the voice gets wrong.

## Calls

### `POST https://readymadeapi.com/v1/voiceover/instant`

Speak up to 2,000 characters and get the MP3 and word timings in the same call, usually within a second.

- Price: $0.00012 per 100 characters, up to 20 per call
- MCP tool: `tts_pro_speak_now`
- Answers in the same call.

Request:

```json
{
  "text": "Your order has shipped and will arrive on Friday.",
  "voice": "af_heart"
}
```

Answer:

```json
{
  "audio_base64": "SUQzBAAAAAAAIlRTU0UAAAAOAAADTGF2ZjYyLjMuMTAwAAAAAAAAAAAAAAD/... (34876 characters)",
  "audio_mime": "audio/mpeg",
  "duration_s": 3.175,
  "words": [
    {
      "word": "Your",
      "start": 0.275,
      "end": 0.425
    },
    {
      "word": "order",
      "start": 0.425,
      "end": 0.65
    },
    {
      "word": "has",
      "start": 0.65,
      "end": 0.863
    },
    {
      "word": "shipped",
      "start": 0.863,
      "end": 1.363
    },
    {
      "word": "and",
      "start": 1.363,
      "end": 1.5
    },
    {
      "word": "will",
      "start": 1.5,
      "end": 1.65
    },
    {
      "word": "arrive",
      "start": 1.65,
      "end": 2.013
    },
    {
      "word": "on",
      "start": 2.013,
      "end": 2.212
    },
    {
      "word": "Friday",
      "start": 2.212,
      "end": 2.9
    }
  ]
}
```

### `POST https://readymadeapi.com/v1/voiceover/speak`

Queue speech for a text. Charged per 100 characters spoken, rounded up; pauses are free.

- Price: $0.00012 per 100 characters, up to 200 per call
- MCP tool: `tts_pro_speak`
- Queued: answers 202 with a job; poll `GET /v1/jobs/{id}`, fetch `GET /v1/jobs/{id}/result`. Charged up front, and what does not run is refunded.

Request:

```json
{
  "text": "Welcome back. <break time=\"500ms\"/> Here is today's update.",
  "voice": "af_heart"
}
```

The finished job:

```json
{
  "job_id": "01a1f553-94c4-730e-9222-464724610044",
  "status": "succeeded",
  "late": false,
  "deadline": "2026-11-20T19:40:57.921846Z",
  "completed_at": "2026-11-19T19:40:59.339674Z",
  "error": null,
  "result": {
    "words": [
      {
        "end": 0.775,
        "word": "Welcome",
        "start": 0.375
      },
      {
        "end": 1.375,
        "word": "back",
        "start": 0.775
      },
      {
        "end": 2.65,
        "word": "Here",
        "start": 2.425
      },
      {
        "end": 2.8,
        "word": "is",
        "start": 2.65
      },
      {
        "end": 3.175,
        "word": "today's",
        "start": 2.8
      },
      {
        "end": 3.9,
        "word": "update",
        "start": 3.175
      }
    ],
    "audio_mime": "audio/mpeg",
    "duration_s": 4.15,
    "audio_base64": "SUQzBAAAAAAAIlRTU0UAAAAOAAADTGF2ZjYyLjMuMTAwAAAAAAAAAAAAAAD/... (45116 characters)"
  }
}
```

## Limits

- Instant call: up to 2,000 characters.
- Queued call: up to 20,000 characters.

## Questions

**Is the answer instant or queued?**

Both. /v1/voiceover/instant speaks up to 2,000 characters in the same call, usually within a second. /v1/voiceover/speak queues up to 20,000 characters.

**Which languages and voices?**

English only, ten voices. American: af_heart, af_bella, af_nicole (female), am_michael, am_fenrir, am_puck (male). British: bf_emma, bf_isabella (female), bm_george, bm_fable (male).

**How is it billed?**

Per 100 characters spoken, rounded up. Pauses are free.

## Using it

- Send `Authorization: Bearer <key>` and a JSON body. Keys and credit: https://readymadeapi.com/account
- Every answer carries `X-Request-Id`, `X-Units` and `X-Charged-Usd`.
- An error is a JSON problem with a `title` to act on and a `detail` in plain words; nothing is charged for it.
- Full schema: https://readymadeapi.com/openapi.json
