> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finesse.flamapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to speech

> Turn text into a clip, or stream it as it is generated.

## One-shot speech

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

<CodeGroup>
  ```ts TypeScript theme={null}
  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
  ```
</CodeGroup>

Identical requests are served from a cache at no charge. Speech is billed per character of `text`.
Every parameter is described in [Synthesize parameters](/voice-api/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`.

<CodeGroup>
  ```ts TypeScript theme={null}
  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);
  ```
</CodeGroup>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.