Streaming audio

On long text, waiting for the whole clip before you hear anything is the slow path. Streaming hands you audio one sentence at a time: play sentence 1 while sentence 2 is still being synthesized, so time-to-first-audio drops from “the whole thing” to “the first sentence.” Each chunk is a complete, independently playable WAV (24 kHz, 16-bit PCM, mono) — the same format as tts.create(), just delivered piece by piece.

When to stream

Situation	Use
Short text (a prompt, a confirmation, a label)	`tts.create()` — one WAV, done.
Long or interactive text (paragraphs, an assistant reply, a call)	`tts.stream()` — start playback after the first sentence.

Streaming doesn’t make total synthesis faster; it makes the first audio arrive sooner. For short inputs there’s no first-sentence advantage to win, so create() is simpler.

SDK — the async iterable

geko.tts.stream(params) takes the same params as create() and returns an async iterable of WAV ArrayBuffers, one per sentence chunk:

for await (const wav of geko.tts.stream({ text: longText, voice: "Aigerim" })) {
  // each `wav` is a standalone WAV chunk — play or buffer it as it arrives
  console.log(`chunk: ${wav.byteLength} bytes`);
}

Play chunks as they land (queue them behind the one that’s currently playing) and the listener hears continuous speech that started ~1 sentence in rather than after the full render.

Streams are not retried. A partial stream can’t be replayed, so unlike tts.create() there’s no automatic retry on a mid-stream failure. Bound the whole stream with a per-call timeout, and cancel with an AbortSignal — see Errors & retries.

Cancelling a stream

Pass a signal to stop synthesis you no longer need (the user interrupted, navigated away, started a new request):

const controller = new AbortController();

const run = (async () => {
  for await (const wav of geko.tts.stream({
    text: longText,
    voice: "Aigerim",
    signal: controller.signal,
    timeout: 60_000, // bound the entire stream, not one chunk
  })) {
    play(wav);
  }
})();

// later — user hits stop:
controller.abort();

abort() propagates as-is; it is not retried or wrapped. A per-call timeout bounds the full stream end-to-end.

The raw HTTP protocol

Non-JS callers hit POST /v1/tts/stream directly. Same JSON body as POST /v1/tts, same auth and metering — only the response shape differs:

Content-Type: application/octet-stream
Header X-Tokay-Stream: wav-frames-v1
Body is a sequence of frames. Each frame is a 4-byte big-endian length, followed by that many bytes of one complete WAV.

Read a length, read that many bytes (that’s one playable WAV chunk), repeat until the stream closes.

import { Geko } from "@gekoai/sdk";

const geko = new Geko({ apiKey: process.env.GEKO_API_KEY });

const longText =
  "Сәлеметсіз бе! Бүгінгі кездесу сағат ондаға белгіленді. " +
  "Егер уақыт сізге ыңғайсыз болса, маған хабарлаңыз.";

for await (const wav of geko.tts.stream({ text: longText, voice: "Aigerim" })) {
  // hand each WAV chunk to your player as it arrives
  play(wav);
}

import os, struct, requests

url = "https://geko--tokay-serve-web.modal.run/v1/tts/stream"
headers = {
    "Authorization": f"Bearer {os.environ['GEKO_API_KEY']}",
    "Content-Type": "application/json",
}
body = {
    "text": (
        "Сәлеметсіз бе! Бүгінгі кездесу сағат ондаға белгіленді. "
        "Егер уақыт сізге ыңғайсыз болса, маған хабарлаңыз."
    ),
    "voice": "Aigerim",
}

with requests.post(url, headers=headers, json=body, stream=True) as res:
    res.raise_for_status()
    raw = res.raw  # frames: 4-byte big-endian length, then that many WAV bytes

    def read_exactly(n: int) -> bytes | None:
        buf = b""
        while len(buf) < n:
            part = raw.read(n - len(buf))
            if not part:
                return None  # stream closed
            buf += part
        return buf

    i = 0
    while True:
        header = read_exactly(4)
        if header is None:
            break  # done
        (length,) = struct.unpack(">I", header)  # big-endian uint32
        wav = read_exactly(length)
        if wav is None:
            break  # truncated stream
        with open(f"chunk_{i}.wav", "wb") as f:
            f.write(wav)  # each chunk is a complete, playable WAV
        i += 1

The non-streaming POST /v1/tts still returns the whole audio/wav in one response, with the billed character count in the X-Tokay-Chars header. /v1/tts/stream bills identically — streaming changes delivery, not price.

Next steps

Voice agents

Pipe an LLM’s reply into streaming TTS for low-latency speech.

Playing & saving audio

Turn each WAV chunk into playback, files, or other formats.

Latency & quality

Drop nfe to 16 and dodge cold starts for faster audio.

Errors & retries

Why streams aren’t retried, and how to bound them.

get started

guides

sdk

reference

Streaming audio

When to stream

SDK — the async iterable

Cancelling a stream

The raw HTTP protocol

Next steps

Voice agents

Playing & saving audio

Latency & quality

Errors & retries

​When to stream

​SDK — the async iterable

​Cancelling a stream

​The raw HTTP protocol

​Next steps

Voice agents

Playing & saving audio

Latency & quality

Errors & retries

When to stream

SDK — the async iterable

Cancelling a stream

The raw HTTP protocol

Next steps