Text to speech

Overtone turns a line of text into expressive 48 kHz speech: the feeling, the laughs and sighs, whispered or shouted words, all written into the text. Try every option on the TTS page before you write code.

curl https://tts-api.yoob.com/v1/audio/speech \
  -H "Authorization: Bearer $YOOB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "yoob-tts-1", "voice": "m0770", "input": "[tender] Hey. [sigh] Whatever happens tomorrow, you are not doing it alone."}' \
  --output line.wav

Voices

Each voice is a designed character. Pass its id as voice. These are the voices the console offers, each with a sample on the TTS page; GET /voices lists every voice the API knows, including 414 more Pro voices with regional accents that are not in this table.

Emotion, sound and delivery tags

Write how the line should sound into the line itself, in lower-case square brackets.

Emotion, at the start of the line

One tag first sets the feeling of the whole line, and the voice's pacing with it: sad, tender and intimate lines are slower. Use the exact names below; common synonyms such as happy or scared are mapped onto them.

Sounds, anywhere

A sound is performed where it stands. One in the middle of a line starts a new chunk there.

Delivery spans, around words

Wrap words to say them a particular way, and close the span: an unclosed span is closed for you, but closed spans render better. [pause] is dropped.

All three together:

[sad] [sigh] I walked past his old office today. [tearful] The nameplate was already gone. [/tearful]

Quality

quality trades the first sound for polish. Long inputs are split into chunks of up to about 40 words, at sentence ends and before mid-line sounds, and every chunk keeps the line's leading emotion.

"pick": "expressive" ranks best takes of an emotion-tagged chunk by how clearly they carry the feeling instead of by overall polish: more emotional, a little less clean.

Output formats

All audio is 48 kHz mono. Choose the container with response_format:

Streaming audio

With "stream": true the response arrives chunk by chunk as each chunk is picked, so playback can start while the rest renders. With pcm, pipe it straight into a player:

curl -N https://tts-api.yoob.com/v1/audio/speech \
  -H "Authorization: Bearer $YOOB_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "yoob-tts-1", "voice": "w1243", "input": "[excited] Okay, okay, do not freak out. [gasp] They want me to start on Monday!", "response_format": "pcm", "stream": true}' \
  | ffplay -f s16le -ar 48000 -ac 1 -nodisp -autoexit -

Response headers describe the render: x-yoob-seed (pass it back as seed to reproduce the audio), x-yoob-quality, x-yoob-sample-rate and x-request-id.

Streaming text in

When the text itself is still being written, by a language model for example, open the speech WebSocket and send the text as it arrives. Each sentence is voiced as soon as it is complete, all in one render that keeps one voice and one seed. It is one connection per reply, and the rate limit counts connections, not sentences.

const ws = new WebSocket("wss://tts-api.yoob.com/v1/audio/speech/stream", {
  headers: { authorization: `Bearer ${process.env.YOOB_API_KEY}` },   // Node; see Authentication for browsers
});
ws.binaryType = "arraybuffer";
ws.onopen = async () => {
  ws.send(JSON.stringify({ voice: "w1243", quality: "best", response_format: "pcm" }));
  for await (const delta of llmReply) ws.send(JSON.stringify({ text: delta }));
  ws.send(JSON.stringify({ end: true }));
};
ws.onmessage = (e) => {
  if (typeof e.data !== "string") return play(e.data);      // 48 kHz s16le audio
  const m = JSON.parse(e.data);                              // ready, chunk, done or error
};

• Text is cut after . ! ? … once the next character arrives, never inside a tag, an open span or an abbreviation such as “Dr.”.
• A later sentence shorter than min_words (3) waits for the next one; the first sentence always goes at once.
• Text that runs past 40 words without a sentence end is cut at its last comma, semicolon or colon.
• {"flush": true} voices whatever is buffered now. 30 s with no message counts as the end; at most 20,000 characters per connection.

Cancelling

Closing the connection cancels a render. When something sits between you and the API that may not pass the close on quickly, give the request your own id and cancel it explicitly, which stops it at once:

# when speaking
-d '{"model": "yoob-tts-1", "voice": "w1243", "input": "...", "request_id": "reply-42"}'

# to stop it
curl https://tts-api.yoob.com/v1/audio/speech/cancel \
  -H "Authorization: Bearer $YOOB_API_KEY" -H "Content-Type: application/json" \
  -d '{"request_id": "reply-42"}'

Ids are 1–64 characters of [A-Za-z0-9._-], unique per key while running. An id cancelled before its request arrives is remembered for 30 s, and that request is refused.

Speed, seed and delivery

Next steps