Stream speech from text (Lightning V3.1)

<Warning>Endpoint scheduled for retirement. This URL will stop accepting requests 60 days from the Lightning v3.1 Pro launch (2026-05-15) — i.e. on 2026-07-14. The Lightning v3.1 model itself is current and stays. Migrate to POST /waves/v1/tts/live and select Lightning v3.1 via the model body field (default).</Warning>

Synthesize speech and stream the audio back over Server-Sent Events. The body and parameters are identical to the sync /get_speech endpoint — the difference is the response is a stream of base64-encoded PCM chunks instead of one binary blob.

When to use this

• Use this when you want playback to start before synthesis is complete — long passages, latency-sensitive UI, live narration.
• Use sync /get_speech when total latency doesn't matter and you'd rather get one buffer.
• Use the WebSocket endpoint when the text arrives incrementally (LLM token stream). SSE assumes you have the full text up front.

How it works

1. POST your text + voice settings — same payload as /get_speech.
2. The response is Content-Type: text/event-stream. Each chunk frame is event: audio\n followed by data: {"audio": "<base64-pcm>"}\n\n.
3. Decode each chunk's audio field with base64 and feed the PCM bytes to your audio pipeline (browser MediaSource, ffmpeg pipe, raw PCM player, etc.).
4. A final data: {"done": true}\n\n frame marks end of stream.

Examples

cURL

curl -N -X POST "https://api.smallest.ai/waves/v1/lightning-v3.1/stream" \
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Streaming this paragraph chunk by chunk so playback can start sooner.",
    "voice_id": "magnus",
    "sample_rate": 24000,
    "output_format": "pcm"
  }'

Python (pip install smallestai>=4.4.0)

import base64
from smallestai import SmallestAI

client = SmallestAI(api_key="YOUR_API_KEY")

with open("stream.pcm", "wb") as f:
    for chunk in client.waves.synthesize_sse_lightning_v3_1(
        text="Streaming this paragraph chunk by chunk so playback can start sooner.",
        voice_id="magnus",
        sample_rate=24000,
        output_format="pcm",
    ):
        # Each chunk is `{"audio": "<base64-encoded PCM>"}`.
        # Decode and pipe to your audio pipeline.
        if chunk.get("audio"):
            f.write(base64.b64decode(chunk["audio"]))

JavaScript / TypeScript (using fetch + a reader)

const res = await fetch("https://api.smallest.ai/waves/v1/lightning-v3.1/stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMALLEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Streaming this paragraph chunk by chunk so playback can start sooner.",
    voice_id: "magnus",
    sample_rate: 24000,
    output_format: "pcm",
  }),
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buf = "";
let finished = false;
while (!finished) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value);
  const events = buf.split("\n\n");
  buf = events.pop() ?? "";
  for (const ev of events) {
    // SSE frames are "event: audio\ndata: {json}" or just "data: {json}".
    // We only care about the data line — pull it out and parse.
    const dataLine = ev.split("\n").find((l) => l.startsWith("data:"));
    if (!dataLine) continue;
    const payload = JSON.parse(dataLine.slice(5).trim());
    if (payload.done) { finished = true; break; }
    if (payload.audio) {
      const pcm = Buffer.from(payload.audio, "base64");
      // … hand pcm to your audio pipeline
    }
  }
}

Common gotchas

• Use a streaming-friendly client. curl -N, Python iter_lines, or a fetch ReadableStream reader. Buffering clients will hide the latency win.
• Audio is base64 inside the event payload, not the raw event bytes. Decode the data.audio field per event.
• output_format=pcm gives the lowest overhead for streaming playback. wav/mp3 work but add per-chunk framing bytes.
• First-chunk latency depends on model warm-up + network distance. Use output_format=pcm and a streaming-friendly client to minimize what you can control.
• JavaScript / TypeScript: the official smallestai npm package predates Lightning v3.1, so call this endpoint with fetch as shown above.