GUIDE

A text to speech API for long texts: chapters, articles and audiobooks

Long texts are where text to speech APIs get slow and expensive. Many limit a request to a few thousand characters, so you split the book yourself, send hundreds of requests and stitch the audio back together, and every character is billed.

The SuperClonica speech API takes up to 20,000 characters in one request and returns one file. In our measurements on the live service about 16,000 characters, 15.6 minutes of speech, came back in 25.6 seconds. This guide shows how to voice a long text and what the limits are.

Pick a narrator Or run the engine yourself

Why it is fast

The server splits the text at sentence boundaries and voices the pieces on several workers at the same time, then joins them into one file with even pauses. A long chapter therefore takes seconds, not minutes, and with "stream": true you can start listening from 300 ms while the rest is made.

How much fits in one request

A request takes up to 20,000 characters, and its audio must fit into your plan's 10-minute window. The plan sets how long one file can be:

  • Free: up to 1 minute, about 1,000 characters.
  • Starter, $5: up to 3 minutes, about 3,000 characters per request.
  • Author, $10: up to 8 minutes.
  • Pro, $20: up to 25 minutes, so the full 20,000 characters.
  • Studio, $50: up to 80 minutes, with room for several long requests at once.

Voice a book chapter by chapter

Split the book at chapters or scenes, send each part as its own request with an Idempotency-Key such as the chapter number, and save each answer as a file. In Python: requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + key, "Idempotency-Key": "chapter-3"}, json={"text": text, "voice": "M2", "language": "en", "format": "mp3"}, timeout=120). A 503 answer means the queue is full: wait the seconds in Retry-After and send the same request again; a repeated key never voices a text twice.

Numbers, dates and abbreviations are read out as words, and line breaks are kept as paragraph breaks.

Choosing the narrator

On a paid plan any voice of the SuperClonica catalog works through the API, and you can train a narrator from your own recording on the site. Hear the candidates free on their pages with a line from your book before you decide. For a private manuscript that must not leave your machine, run the free SuperClonica engine yourself instead; it voices long texts the same way.