Skip to main content
This example takes a multi-paragraph script and produces a single audio file. It demonstrates the SDK’s automatic chunking: you pass the whole script to create_speech, the SDK splits at sentence boundaries, generates each segment, and merges the result.

Python

TypeScript

What happens under the hood

  1. The SDK detects that SCRIPT.length > 300.
  2. It splits on sentence punctuation first, then word boundaries if a sentence is itself too long.
  3. The Python SDK fires up to 3 parallel create_speech requests; the TypeScript SDK runs them sequentially.
  4. Each segment returns a complete audio file.
  5. The SDK strips the WAV header from every segment after the first and concatenates the bytes into a single continuous clip.
  6. You get one playable file back, identical in form to a single-segment response.

Tips

  • Punctuation pays off. Well-punctuated source text produces cleaner cuts. If your script comes from machine translation or transcription, adding ./?/! improves the result.
  • Voice settings travel. The same voice_settings are applied to every segment, so the merged audio sounds consistent.
  • Estimate first. predict_duration doesn’t auto-chunk, but you can split your script into a few sentences, call predict_duration on each, and sum the durations to estimate cost.
  • Pick the right model. For long narration, sona_speech_2 produces the most natural delivery. Switch to sona_speech_2_flash if you need to generate many narrations quickly.

Long text

Full reference on the 300-character limit and chunking behavior.

Voice settings

Tune the delivery of your narration.