Text to speech - Finesse

One-shot speech

speech.create returns the whole clip in one response, for up to 10,000 characters of text.

const audio = await client.speech.create({
  voice_id: voice.id,
  text: "The quick brown fox jumps over the lazy dog.",
  language: "en", // optional; defaults to the voice's language
  output_format: "wav", // default; or raw PCM: "s16le", "s24le", "s32le", "f32le", "f64le"
  num_step: 32, // optional; fewer steps is faster, more is higher quality
});

audio.data; // Uint8Array
audio.contentType; // "audio/wav"
audio.sampleRate; // 24000
audio.generationId; // id of this clip in your generation history
audio.audioURL; // stored copy of the clip, when storage is enabled

Identical requests are served from a cache at no charge. Speech is billed per character of text. Every parameter is described in Synthesize parameters.

Streaming speech

speech.stream sends audio as it is generated, so playback can start before the whole clip is ready. Chunks are raw PCM (s16le, 24 kHz, mono) unless you set output_format.

const stream = client.speech.stream({ voice_id: voice.id, text: "Hello, streamed." });
for await (const chunk of stream) {
  speaker.write(chunk.pcm);
}
console.log(stream.done?.audio_duration_s, stream.done?.generation_id);

To collect everything instead, call readAll(). Errors before the stream starts are the usual errors (for example PaymentRequiredError). A failure after it starts is a StreamError.

Audio formats

`output_format`	What you get	Default for
`wav`	WAV file	`speech.create`
`s16le`	Raw PCM, 16-bit signed little-endian	`speech.stream`, realtime
`s24le`, `s32le`	Raw PCM, 24- or 32-bit signed
`f32le`, `f64le`	Raw PCM, 32- or 64-bit float
`opus`	Opus	realtime only

All audio is mono. The engine’s native rate is 24 kHz. You can ask for a higher sample_rate, but lower ones still come back at 24 kHz, so always read the actual rate from the response: the audio’s or stream’s sample rate, or the realtime task_started event.