Input streaming

When to use it

Use this API when the text is still being produced — typically an LLM’s token stream. Rather than buffering output into sentences and synthesizing one at a time, the server consumes fragments as they arrive and holds back only a few words: the model generates each audio chunk from everything already spoken plus a short lookahead, so it never needs a complete sentence.

• Speech starts 8 words into the stream with the default settings, mid-sentence, rather than waiting for the first sentence to end: ~80 ms to first audio
• Prosody is continuous across chunk seams — each chunk is generated with the preceding audio as context, so there are no restarts or intonation resets at chunk boundaries
• One connection carries one utterance, and it can be opened before the text exists — while the user is still speaking — so DNS, TLS and admission are off the critical path. Opening the socket ahead of time (the Python SDK’s speech.prepare()) is the fastest path to first audio

Two WebSocket endpoints expose this: a native one (recommended) and an ElevenLabs-compatible one for existing EL integrations. Both authenticate with your usual header on the upgrade request; see Authentication.

Native WebSocket

Connect with query parameters, send text fragments as JSON messages the moment they’re produced, and read binary frames back: raw PCM, 16-bit LE mono at 24 kHz. The server chunks at safe boundaries and keeps rolling text-and-audio context, so chunk N+1 continues chunk N’s prosody. Don’t pre-chunk or sentence-split yourself.

Messages you send

Messages you receive

import asyncio
from openai import AsyncOpenAI
from svara import AsyncSvara

llm = AsyncOpenAI()
svara = AsyncSvara()                      # reads SVARA_API_KEY


async def speak(prompt: str):
    async def deltas():
        stream = await llm.chat.completions.create(
            model="gpt-4o-mini", stream=True,
            messages=[{"role": "user", "content": prompt}])
        async for event in stream:
            if event.choices[0].delta.content:
                yield event.choices[0].delta.content

    # One WebSocket; audio starts a few words into the LLM's output.
    async for audio in svara.speech.stream_input(deltas(), voice="sv_enhdbrj5"):
        player.feed(audio)                # PCM16 @ 24 kHz mono

asyncio.run(speak("Explain how rainbows form, in three sentences."))

Eager mode

mode=eager is the lowest-latency configuration and maps directly onto how the model was trained. The server buffers incoming deltas at word granularity (mid-word token deltas are handled). Once enough complete words exist it synthesizes the first chunk_words with the next few words attached as the lookahead peek. Measured against production, first audio needs max(2 × chunk_words, chunk_words + peek_words) words:

Chinese and Japanese are written without spaces, so there the server counts one word per two characters and prefers to cut at 。！？，、.

With defaults, speech starts 8 words into the LLM’s output (9 with peek_words=5); typically well before the first sentence ends. An idle socket is not reaped on a short timer — one left open for five minutes still synthesized normally — so opening early is safe.

ElevenLabs-compatible WebSocket

A drop-in implementation of the ElevenLabs realtime protocol, for existing EL integrations: the official EL SDKs’ WebSocket clients work unmodified. The full protocol is supported:

• BOS: {"text": " ", "generation_config": {"chunk_length_schedule": [120,160,250,290]}} (schedule values clamped 50-500; auto_mode supported)
• Text: {"text": "fragment ", "try_trigger_generation": true}, plus {"flush": true}; a bare space is a keepalive
• EOS: {"text": ""}
• Audio frames: {"audio": "<base64>", "alignment": …, "normalizedAlignment": …} in the negotiated output_format (query param, e.g. pcm_24000, mp3_44100_128), then {"isFinal": true} and a clean close (code 1000)
• inactivity_timeoutquery param: 20 s default, 180 s max

Character timings in alignment are chunk-relative and approximate: chunk boundaries are sample-exact, characters uniform within a chunk.

Tips

• Forward raw deltas. Don’t sentence-split, batch, or “clean up” the LLM stream client-side; the server’s chunker is the one that knows the model’s trained format.
• Buffer ~150 ms on playback. A small jitter buffer on your audio sink absorbs network variance without hurting perceived latency.
• Keep the socket warm for turns, not sessions. Open the connection when a reply starts, close on {"type": "done"}. Each connection is one utterance with one prosodic arc.
• Concurrent conversations need concurrent streams: each open socket counts against your plan’s concurrency limit (see Rate limits).