Long Text Input - Inworld AI Documentation

The synchronous TTS API accepts up to 2,000 characters per request. For longer content — articles, book chapters, scripts — you have two options.

Start with the Async API, which accepts up to 100,000 characters. Submit the text as one job and the server chunks, synthesizes, and stitches it for you, then hands back a single audio file to download. There is no pipeline to maintain and no seams to tune.

Chunk it yourself when you need something a job cannot give you: text beyond 100,000 characters, control over where the splits land, or audio as it is produced rather than at the end. We provide ready-to-run scripts in Python and JavaScript that handle that entire pipeline for you.

How the Scripts Work

Chunk the text

The input is split into segments under the 2,000-character API limit. The chunking algorithm looks for natural break points in the following priority order:

Paragraph breaks (\n\n)
Line breaks (\n)
Sentence endings (. ! ?)
Last space (fallback)

This ensures audio segments end at natural pauses, producing smooth-sounding output.

Synthesize each chunk

Each chunk is sent to the TTS API with controlled concurrency and automatic retry logic for rate limits. Chunks are processed in parallel (default: 2 concurrent requests) to speed up synthesis while respecting API rate limits.

Stitch the audio

The individual audio responses are combined into a single output file. The Python script produces a WAV file with configurable silence between segments, while the JavaScript script produces an MP3 file and uses ffmpeg to merge segments with correct duration metadata.

Configuration

Both scripts share the same tunable parameters:

Parameter	Default	Description
`MIN_CHUNK_SIZE`	500	Minimum characters before looking for a break point
`MAX_CHUNK_SIZE`	1,900	Maximum chunk size (stays under the 2,000-char API limit)
`MAX_CONCURRENT_REQUESTS`	2	Parallel API requests (increase with caution to avoid rate limits)
`MAX_RETRIES`	3	Retry attempts for rate-limited requests with exponential backoff

Running the Scripts

Prerequisites

An Inworld API key set as the INWORLD_API_KEY environment variable
A text file with your long-form content
Python 3 (for the Python script) or Node.js (for the JavaScript script)
ffmpeg (optional, for the JS script — produces correct MP3 duration metadata)

Python

export INWORLD_API_KEY=your_api_key_here
pip install requests python-dotenv
python example_tts_long_input.py

The script reads the input text file, chunks it, synthesizes all chunks with the Inworld TTS API, and saves the combined audio as a WAV file. It also prints a splice report showing the exact timestamps where chunks were joined, useful for quality checking.

JavaScript

export INWORLD_API_KEY=your_api_key_here
node example_tts_long_input_compressed.js

The script follows the same chunking and synthesis pipeline, outputting a compressed MP3 file. When ffmpeg is available, it merges segments with correct duration metadata. Otherwise, it falls back to raw concatenation.

Code Examples

Python

WAV output with splice report and configurable silence between segments

JavaScript

Compressed MP3 output with ffmpeg-based segment merging

Next Steps

Synthesize Speech (Async)

Submit up to 100,000 characters as one job and skip the pipeline.

Synthesize Speech

Learn about the standard (non-streaming) synthesis API.

Streaming API

Use streaming for real-time playback of shorter content.

Latency Best Practices

Optimize time-to-first-audio for real-time use cases.

​How the Scripts Work

​Configuration

​Running the Scripts

​Prerequisites

​Python

​JavaScript

​Code Examples

Python

JavaScript

​Next Steps

Synthesize Speech (Async)

Synthesize Speech

Streaming API

Latency Best Practices

How the Scripts Work

Configuration

Running the Scripts

Prerequisites

Python

JavaScript

Code Examples

Next Steps