Python SDK

The inworld-tts Python SDK wraps the Inworld TTS REST API with a clean, Pythonic interface. It handles chunking for long text, retries with exponential backoff, and connection management automatically — reducing typical integrations from 30+ lines of raw HTTP to just a few lines of code.

pip install inworld-tts

Requires Python 3.10+.

Quick Start

from inworld_tts import InworldTTS

tts = InworldTTS()  # reads INWORLD_API_KEY from env

tts.generate(
    text="What a wonderful day to be a text-to-speech model!",
    voice="Ashley",
    output_file="output.mp3",
)

Speech Synthesis

generate(options)

Synthesize speech and return the complete audio as bytes. Text longer than 2,000 characters is automatically chunked and sent in parallel.

audio = tts.generate(
    text="Hello, world!",
    voice="Ashley",
    model="inworld-tts-2",
    encoding="MP3",
    output_file="output.mp3",  # optional — also writes to disk
)

Returns: bytes — raw audio bytes in the requested encoding.

stream(options)

Stream audio chunks over HTTP as they are generated. Lower time-to-first-audio than generate(). Text of any length is accepted: longer input is split at sentence boundaries and streamed as sequential requests. See Long Text.

chunks = []

async for chunk in tts.stream(
    text="Streaming is great for real-time playback!",
    voice="Ashley",
):
    chunks.append(chunk)

audio = b"".join(chunks)

Parameters are the same as generate(), plus an optional max_chunk_chars that overrides the default 3,900-character chunk ceiling. See Long Text.

Yields: bytes — audio chunks as they arrive.

generate_with_timestamps(options)

Same as generate() but also returns word- or character-level timing data. Useful for lip-sync, karaoke, and subtitle alignment.

result = tts.generate_with_timestamps(
    text="Timestamps are useful for lip sync.",
    voice="Ashley",
    timestamp_type="WORD",
)

# result.audio → bytes
# result.timestamps.word_alignment.words → ["Timestamps", "are", "useful", ...]
# result.timestamps.word_alignment.word_start_time_seconds → [0.0, 0.42, 0.61, ...]

Takes all the same parameters as generate(), plus:

Returns: an object with audio: bytes and timestamps: TimestampInfo.

stream_with_timestamps(options)

Stream audio chunks, each paired with optional timestamp data. Text of any length is accepted: longer input is split at sentence boundaries and streamed as sequential requests. See Long Text.

async for chunk in tts.stream_with_timestamps(
    text="Streaming with timestamps!",
    voice="Ashley",
    timestamp_type="WORD",
):
    # chunk.audio: bytes
    # chunk.timestamps: TimestampInfo | None
    pass

Takes all the same parameters as stream(), plus timestamp_type (required).

Yields: objects with audio: bytes and optional timestamps: TimestampInfo.

play(audio, options)

Play audio from bytes or a file path. Encoding is auto-detected from magic bytes unless overridden.

audio = tts.generate(text="Listen to this!", voice="Ashley")
tts.play(audio)

# Or play from a file
tts.play("output.mp3")

Voice Management

list_voices(options)

List available voices, optionally filtered by language.

voices = tts.list_voices()

# Filter by language
en_voices = tts.list_voices(lang="EN_US")
multi_lang = tts.list_voices(lang=["EN_US", "ES_ES"])

Returns: list[VoiceInfo]

get_voice(voice)

Get details for a single voice. Works with custom voices in your workspace (cloned or designed voices).

voice = tts.get_voice("my-custom-voice-id")
# voice.voice_id, voice.display_name, voice.lang_code, ...

Returns: VoiceInfo

clone_voice(options)

Clone a voice from one or more audio recordings — as little as 3 seconds works, and longer samples (up to 30 seconds) improve similarity.

result = tts.clone_voice(
    audio_samples=["./recording.wav"],
    display_name="My Cloned Voice",
    lang="EN_US",
)

print(result.voice.voice_id)  # use this ID in generate()

Returns: CloneVoiceResult — the cloned voice ID is at result.voice.voice_id.

design_voice(options)

Design a new voice from a text description — no audio recording needed.

result = tts.design_voice(
    design_prompt="A warm, friendly female voice with a slight British accent",
    preview_text="Hello! Welcome to our application.",
    number_of_samples=3,
)

# Listen to previews, then publish the one you like
chosen_voice = result.preview_voices[0]

Returns: DesignVoiceResult — preview voices at result.preview_voices.

publish_voice(options)

Publish a designed or cloned voice preview to your library so it can be used in generate() and stream().

voice = tts.publish_voice(
    voice=chosen_voice.voice_id,
    display_name="My Designed Voice",
)

Returns: VoiceInfo

migrate_from_elevenlabs(options)

Migrate a voice from ElevenLabs to your Inworld workspace. Fetches the voice's audio samples directly from ElevenLabs and clones them into Inworld. No ElevenLabs SDK required.

import os

result = tts.migrate_from_elevenlabs(
    eleven_labs_api_key=os.environ["ELEVEN_LABS_API_KEY"],
    eleven_labs_voice_id="abc123",
)

print(f'Migrated "{result.eleven_labs_name}" → {result.inworld_voice_id}')

Returns: an object with eleven_labs_voice_id, eleven_labs_name, and inworld_voice_id.

Configuration

Create a client with InworldTTS():

from inworld_tts import InworldTTS

tts = InworldTTS()                   # reads INWORLD_API_KEY from env
tts = InworldTTS(api_key="your_key") # or pass explicitly

Long Text

generate() and generate_with_timestamps() automatically chunk text longer than 2,000 characters and send chunks in parallel (controlled by max_concurrent_requests). The resulting audio is seamlessly concatenated, and timestamp offsets are merged correctly.

stream() and stream_with_timestamps() accept text of any length. The streaming endpoint takes up to 4,000 characters per request, so the SDK splits longer input at sentence boundaries into chunks of at most 3,900 characters and streams them as sequential requests. The audio arrives as one continuous sequence of chunks.

The 100-character margin is deliberate. The SDK splits on estimated audio-equivalent length, where a <break> tag counts as roughly 12 characters per second of silence and each CJK character counts as three. That estimate can differ from the raw character count the endpoint enforces.

To set your own ceiling, pass max_chunk_chars. The SDK does not check it against the endpoint limit, so a value above 4,000 produces requests that the API rejects.

Error Handling

The SDK exports three error classes, all extending InworldTTSError:

from inworld_tts import (
    InworldTTS,
    InworldTTSError,
    ApiError,
    NetworkError,
    MissingApiKeyError,
)

tts = InworldTTS()  # reads INWORLD_API_KEY from env

try:
    audio = tts.generate(text="Hello!", voice="Ashley")
except MissingApiKeyError:
    # No API key provided
    pass
except ApiError as err:
    print(f"HTTP {err.code}: {err.message}", err.details)
except NetworkError as err:
    print(f"Network error: {err}")

Next Steps