Lightning v3.1 SSE (endpoint will be deprecated)

<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`](/waves/api-reference/api-reference/text-to-speech/synthesize-speech-sse) 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** ```bash 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`) ```python 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) ```typescript 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.