TTSWave API documentation

Authorization: Bearer tts_your_key_here

X-API-Key: tts_your_key_here

X-TTS-Session: listener-8f3a2c
X-TTS-Order: 3

export TTSWAVE_API_KEY="tts_your_key_here"

curl https://api.ttswave.stream/v1/audio/speech \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello! This is my first sentence from TTSWave.", "response_format": "mp3"}' \
  -o hello.mp3

// Node 18+ (built-in fetch). Save as quickstart.mjs, run: node quickstart.mjs
import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.ttswave.stream/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "Hello! This is my first sentence from TTSWave.",
    response_format: "mp3",
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.status} ${error.code}: ${error.message}`);
}
await writeFile("hello.mp3", Buffer.from(await res.arrayBuffer()));
console.log("Saved hello.mp3");

# pip install requests
import os
import requests

r = requests.post(
    "https://api.ttswave.stream/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"},
    json={"input": "Hello! This is my first sentence from TTSWave.", "response_format": "mp3"},
    timeout=60,
)
if not r.ok:
    err = r.json()["error"]
    raise RuntimeError(f"{err['status']} {err['code']}: {err['message']}")
with open("hello.mp3", "wb") as f:
    f.write(r.content)
print("Saved hello.mp3")

<?php
// PHP 8+ with the curl extension. Save as quickstart.php, run: php quickstart.php
$ch = curl_init("https://api.ttswave.stream/v1/audio/speech");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "input" => "Hello! This is my first sentence from TTSWave.",
        "response_format" => "mp3",
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    $error = json_decode($body, true)["error"];
    throw new RuntimeException("{$error['status']} {$error['code']}: {$error['message']}");
}
file_put_contents("hello.mp3", $body);
echo "Saved hello.mp3\n";

// Go 1.21+, standard library only. Save as main.go, run: go run main.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"input":           "Hello! This is my first sentence from TTSWave.",
		"response_format": "mp3",
	})
	req, _ := http.NewRequest("POST", "https://api.ttswave.stream/v1/audio/speech", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 60 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	data, err := io.ReadAll(res.Body)
	if err != nil {
		log.Fatal(err)
	}
	if res.StatusCode != http.StatusOK {
		var e struct {
			Error struct {
				Code    string `json:"code"`
				Message string `json:"message"`
				Status  int    `json:"status"`
			} `json:"error"`
		}
		json.Unmarshal(data, &e)
		log.Fatalf("%d %s: %s", e.Error.Status, e.Error.Code, e.Error.Message)
	}
	if err := os.WriteFile("hello.mp3", data, 0o644); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Saved hello.mp3")
}

// Java 11+, no dependencies. Save as Quickstart.java, run: java Quickstart.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;

public class Quickstart {
    public static void main(String[] args) throws Exception {
        String json = "{\"input\": \"Hello! This is my first sentence from TTSWave.\", \"response_format\": \"mp3\"}";
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/audio/speech"))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(60))
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<byte[]> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofByteArray());
        if (res.statusCode() != 200) {
            // The body is the JSON error envelope: {"error": {"code": ..., "message": ..., "status": ...}}
            throw new RuntimeException(res.statusCode() + " " + new String(res.body()));
        }
        Files.write(Path.of("hello.mp3"), res.body());
        System.out.println("Saved hello.mp3");
    }
}

// .NET 8: dotnet new console, replace Program.cs with this, run: dotnet run
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var res = await http.PostAsJsonAsync("https://api.ttswave.stream/v1/audio/speech", new
{
    input = "Hello! This is my first sentence from TTSWave.",
    response_format = "mp3",
});
if (!res.IsSuccessStatusCode)
{
    var error = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("error");
    throw new Exception($"{error.GetProperty("status")} {error.GetProperty("code")}: {error.GetProperty("message")}");
}
await File.WriteAllBytesAsync("hello.mp3", await res.Content.ReadAsByteArrayAsync());
Console.WriteLine("Saved hello.mp3");

curl https://api.ttswave.stream/v1/voices \
  -H "Authorization: Bearer $TTSWAVE_API_KEY"

const res = await fetch("https://api.ttswave.stream/v1/voices", {
  headers: { Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}` },
});
const { default: defaultVoice, voices } = await res.json();
const usable = voices.filter((v) => v.available);
console.log(defaultVoice, usable.map((v) => `${v.id} (${v.accent}, ${v.gender})`));

import os
import requests

r = requests.get(
    "https://api.ttswave.stream/v1/voices",
    headers={"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"},
    timeout=10,
)
r.raise_for_status()
data = r.json()
print(data["default"], [v["id"] for v in data["voices"] if v["available"]])

<?php
$ch = curl_init("https://api.ttswave.stream/v1/voices");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("TTSWAVE_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    throw new RuntimeException($data["error"]["code"] ?? curl_error($ch));
}
echo "default: {$data['default']}\n";
foreach ($data["voices"] as $v) {
    if ($v["available"]) {
        echo "{$v['id']} ({$v['accent']}, {$v['gender']})\n";
    }
}

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

type Voice struct {
	ID        string `json:"id"`
	Accent    string `json:"accent"`
	Gender    string `json:"gender"`
	Realtime  bool   `json:"realtime"`
	Available bool   `json:"available"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.ttswave.stream/v1/voices", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	res, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		log.Fatalf("GET /v1/voices: %s", res.Status)
	}
	var data struct {
		Default string  `json:"default"` // "" when null
		Voices  []Voice `json:"voices"`
	}
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	fmt.Println("default:", data.Default)
	for _, v := range data.Voices {
		if v.Available {
			fmt.Printf("%s (%s, %s)\n", v.ID, v.Accent, v.Gender)
		}
	}
}

// Java 11+. Save as Voices.java, run: java Voices.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Voices {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/voices"))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 200) throw new RuntimeException(res.statusCode() + " " + res.body());

        // Dependency-free parsing for this flat structure; in a real project use Jackson or Gson.
        System.out.println("default: " + field(res.body(), "default"));
        Matcher voice = Pattern.compile("\\{[^{}]*\\}").matcher(res.body()); // each voice object
        while (voice.find()) {
            String v = voice.group();
            if (v.matches("(?s).*\"available\"\\s*:\\s*true.*")) {
                System.out.println(field(v, "id") + " (" + field(v, "accent") + ", " + field(v, "gender") + ")");
            }
        }
    }

    static String field(String json, String name) {
        Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*\"([^\"]*)\"").matcher(json);
        return m.find() ? m.group(1) : null;
    }
}

using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

// GetStringAsync throws HttpRequestException on a non-2xx status.
using var doc = JsonDocument.Parse(await http.GetStringAsync("https://api.ttswave.stream/v1/voices"));
Console.WriteLine($"default: {doc.RootElement.GetProperty("default")}");
foreach (var v in doc.RootElement.GetProperty("voices").EnumerateArray())
{
    if (v.GetProperty("available").GetBoolean())
        Console.WriteLine($"{v.GetProperty("id")} ({v.GetProperty("accent")}, {v.GetProperty("gender")})");
}

{
  "default": "us-female-heart",
  "voices": [
    {"id": "us-female-heart", "label": "Heart (warm, default)", "engine": "kokoro", "voice": "af_heart",
     "lang": "en-us", "accent": "American", "gender": "female", "grade": "A",
     "realtime": true, "available": true},
    {"id": "uk-male-george", "label": "George", "engine": "kokoro", "voice": "bm_george",
     "lang": "en-gb", "accent": "British", "gender": "male", "grade": "C",
     "realtime": true, "available": true}
  ],
  "rawKokoroVoices": []
}

curl https://api.ttswave.stream/v1/audio/speech \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Your order has shipped.", "voice": "us-male-michael", "response_format": "mp3"}' \
  -o shipped.mp3

import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.ttswave.stream/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Your order has shipped.", voice: "us-male-michael", response_format: "mp3" }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile("shipped.mp3", Buffer.from(await res.arrayBuffer()));

import os
import requests

r = requests.post(
    "https://api.ttswave.stream/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"},
    json={"input": "Your order has shipped.", "voice": "us-male-michael", "response_format": "mp3"},
    timeout=120,
)
r.raise_for_status()
with open("shipped.mp3", "wb") as f:
    f.write(r.content)

<?php
$ch = curl_init("https://api.ttswave.stream/v1/audio/speech");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "input" => "Your order has shipped.",
        "voice" => "us-male-michael",
        "response_format" => "mp3",
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    $error = json_decode($body, true)["error"];
    throw new RuntimeException("{$error['code']}: {$error['message']}");
}
file_put_contents("shipped.mp3", $body);

package main

import (
	"bytes"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"input":           "Your order has shipped.",
		"voice":           "us-male-michael",
		"response_format": "mp3",
	})
	req, _ := http.NewRequest("POST", "https://api.ttswave.stream/v1/audio/speech", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := (&http.Client{Timeout: 120 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	data, err := io.ReadAll(res.Body)
	if err != nil {
		log.Fatal(err)
	}
	if res.StatusCode != http.StatusOK {
		log.Fatalf("%s: %s", res.Status, data) // data is the JSON error envelope
	}
	if err := os.WriteFile("shipped.mp3", data, 0o644); err != nil {
		log.Fatal(err)
	}
}

// Java 11+. Save as Speech.java, run: java Speech.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;

public class Speech {
    public static void main(String[] args) throws Exception {
        String json = "{\"input\": \"Your order has shipped.\", \"voice\": \"us-male-michael\", \"response_format\": \"mp3\"}";
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/audio/speech"))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(120))
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<byte[]> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofByteArray());
        if (res.statusCode() != 200) throw new RuntimeException(res.statusCode() + " " + new String(res.body()));
        Files.write(Path.of("shipped.mp3"), res.body());
    }
}

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var res = await http.PostAsJsonAsync("https://api.ttswave.stream/v1/audio/speech", new
{
    input = "Your order has shipped.",
    voice = "us-male-michael",
    response_format = "mp3",
});
if (!res.IsSuccessStatusCode)
{
    var error = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("error");
    throw new Exception($"{error.GetProperty("code")}: {error.GetProperty("message")}");
}
await File.WriteAllBytesAsync("shipped.mp3", await res.Content.ReadAsByteArrayAsync());

{"type":"start","provider":"local-kokoro","voice":"us-female-heart","sampleRate":24000,"sentences":[{"index":0,"text":"Hello, and welcome to the demo."},{"index":1,"text":"This is a short test of the speech engine."}]}
{"type":"mark","index":0,"text":"Hello, and welcome to the demo.","startMs":0,"durationMs":2140,"cached":false}
{"type":"audio","format":"pcm_s16le","data":"AAABAAIA...","sampleRate":24000,"channels":1}
{"type":"audio","format":"pcm_s16le","data":"...","sampleRate":24000,"channels":1}
{"type":"mark","index":1,"text":"This is a short test of the speech engine.","startMs":2140,"durationMs":2650,"cached":false}
{"type":"audio","format":"pcm_s16le","data":"...","sampleRate":24000,"channels":1}
{"type":"done","provider":"local-kokoro","durationMs":4790,"browser":false}

# -N disables buffering so frames print as they arrive
curl -N https://api.ttswave.stream/v1/tts/stream \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, and welcome to the demo. This is a short test of the speech engine."}'

// Your backend: Node 18+ with Express. The browser calls POST /api/speech;
// only this server knows the TTSWave key.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/speech", async (req, res) => {
  // Check your own user's session and limits here.
  const text = String(req.body?.text ?? "").slice(0, 8000);
  const abort = new AbortController();
  res.on("close", () => abort.abort()); // user went away: stop the upstream stream

  try {
    const upstream = await fetch("https://api.ttswave.stream/v1/tts/stream", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ text }), // add voice: "..." to pick a voice
      signal: abort.signal,
    });
    if (!upstream.ok) {
      // Errors arrive as JSON before any frame. Pass on the code, never the key.
      const { error } = await upstream.json();
      return res.status(upstream.status).json({ error: error.code });
    }
    res.setHeader("Content-Type", "application/x-ndjson");
    res.setHeader("Cache-Control", "no-store");
    res.setHeader("X-Accel-Buffering", "no"); // if nginx sits in front of your app
    for await (const chunk of upstream.body) res.write(chunk); // forward frames unchanged
    res.end();
  } catch (err) {
    if (!res.headersSent) res.status(502).json({ error: "tts_unreachable" });
    else res.end();
  }
});

app.listen(3000);

# Save a stream as a WAV file. pip install requests
import base64
import json
import os
import wave

import requests

with requests.post(
    "https://api.ttswave.stream/v1/tts/stream",
    headers={"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"},
    json={"text": "Hello, and welcome to the demo. This is a short test of the speech engine."},
    stream=True,
    timeout=(5, 60),  # connect, per-read
) as r:
    if r.status_code != 200:
        err = r.json()["error"]
        raise RuntimeError(f"{err['code']}: {err['message']}")
    with wave.open("speech.wav", "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)       # 16-bit
        wav.setframerate(24000)
        for line in r.iter_lines():
            if not line:
                continue
            frame = json.loads(line)
            if frame["type"] == "mark":
                print(f"{frame['startMs']:>6} ms  {frame['text']}")
            elif frame["type"] == "audio":
                wav.writeframes(base64.b64decode(frame["data"]))
            elif frame["type"] == "error":
                raise RuntimeError(f"{frame['code']}: {frame['message']}")

<?php
// Save a stream as a WAV file. PHP 8+ with the curl extension.
$pcm = "";        // decoded audio so far
$buffer = "";     // bytes received but not yet split into lines
$failure = null;  // error frame, if synthesis fails mid-stream

$handleFrame = function (array $frame) use (&$pcm, &$failure) {
    if ($frame["type"] === "mark") {
        printf("%6d ms  %s\n", $frame["startMs"], $frame["text"]);
    } elseif ($frame["type"] === "audio") {
        $pcm .= base64_decode($frame["data"]);
    } elseif ($frame["type"] === "error") {
        $failure = "{$frame['code']}: {$frame['message']}";
    }
};

$ch = curl_init("https://api.ttswave.stream/v1/tts/stream");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "text" => "Hello, and welcome to the demo. This is a short test of the speech engine.",
    ]),
    CURLOPT_TIMEOUT => 300,
    // Called for every chunk as it arrives: split it into NDJSON lines.
    CURLOPT_WRITEFUNCTION => function ($ch, string $chunk) use (&$buffer, $handleFrame) {
        $buffer .= $chunk;
        if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
            return strlen($chunk); // an error envelope, handled below
        }
        while (($nl = strpos($buffer, "\n")) !== false) {
            $line = trim(substr($buffer, 0, $nl));
            $buffer = substr($buffer, $nl + 1);
            if ($line !== "") {
                $handleFrame(json_decode($line, true));
            }
        }
        return strlen($chunk);
    },
]);
if (curl_exec($ch) === false) {
    throw new RuntimeException(curl_error($ch));
}
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    $error = json_decode($buffer, true)["error"];
    throw new RuntimeException("{$error['code']}: {$error['message']}");
}
if ($failure !== null) {
    throw new RuntimeException($failure);
}

// 44-byte WAV header: PCM, mono, 24 000 Hz, 16-bit.
$header = pack("A4VA4A4VvvVVvvA4V", "RIFF", 36 + strlen($pcm), "WAVE", "fmt ",
    16, 1, 1, 24000, 48000, 2, 16, "data", strlen($pcm));
file_put_contents("speech.wav", $header . $pcm);

// Save a stream as a WAV file. Go 1.21+, standard library only.
package main

import (
	"bytes"
	"encoding/binary"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

type Frame struct {
	Type    string `json:"type"`
	Text    string `json:"text"`
	StartMs int    `json:"startMs"`
	Data    []byte `json:"data"` // base64 in the JSON, decoded automatically
	Code    string `json:"code"`
	Message string `json:"message"`
}

func main() {
	body := strings.NewReader(`{"text": "Hello, and welcome to the demo. This is a short test of the speech engine."}`)
	req, _ := http.NewRequest("POST", "https://api.ttswave.stream/v1/tts/stream", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		log.Fatalf("%s: %s", res.Status, msg)
	}

	var pcm bytes.Buffer
	dec := json.NewDecoder(res.Body) // reads one NDJSON frame at a time, as it arrives
	for {
		var f Frame
		if err := dec.Decode(&f); err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}
		switch f.Type {
		case "mark":
			fmt.Printf("%6d ms  %s\n", f.StartMs, f.Text)
		case "audio":
			pcm.Write(f.Data)
		case "error":
			log.Fatalf("%s: %s", f.Code, f.Message)
		}
	}
	if err := os.WriteFile("speech.wav", append(wavHeader(pcm.Len()), pcm.Bytes()...), 0o644); err != nil {
		log.Fatal(err)
	}
}

// wavHeader returns a 44-byte WAV header for n bytes of 24 kHz mono 16-bit PCM.
func wavHeader(n int) []byte {
	h := make([]byte, 44)
	copy(h[0:], "RIFF")
	binary.LittleEndian.PutUint32(h[4:], uint32(36+n))
	copy(h[8:], "WAVEfmt ")
	binary.LittleEndian.PutUint32(h[16:], 16)
	binary.LittleEndian.PutUint16(h[20:], 1)     // PCM
	binary.LittleEndian.PutUint16(h[22:], 1)     // mono
	binary.LittleEndian.PutUint32(h[24:], 24000) // sample rate
	binary.LittleEndian.PutUint32(h[28:], 48000) // bytes per second
	binary.LittleEndian.PutUint16(h[32:], 2)     // bytes per sample
	binary.LittleEndian.PutUint16(h[34:], 16)    // bits per sample
	copy(h[36:], "data")
	binary.LittleEndian.PutUint32(h[40:], uint32(n))
	return h
}

// Save a stream as a WAV file. Java 11+. Save as StreamToWav.java, run: java StreamToWav.java
import java.io.ByteArrayOutputStream;
import java.io.FileOutputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.util.Base64;
import java.util.Iterator;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class StreamToWav {
    public static void main(String[] args) throws Exception {
        String json = "{\"text\": \"Hello, and welcome to the demo. This is a short test of the speech engine.\"}";
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/tts/stream"))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        // ofLines() hands over each NDJSON frame as soon as its line arrives.
        HttpResponse<Stream<String>> res =
                HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofLines());
        if (res.statusCode() != 200) {
            throw new RuntimeException(res.statusCode() + " " + res.body().collect(Collectors.joining()));
        }

        ByteArrayOutputStream pcm = new ByteArrayOutputStream();
        for (Iterator<String> lines = res.body().iterator(); lines.hasNext(); ) {
            String frame = lines.next();
            String type = field(frame, "type");
            if ("mark".equals(type)) {
                System.out.printf("%6s ms  %s%n", number(frame, "startMs"), field(frame, "text"));
            } else if ("audio".equals(type)) {
                pcm.write(Base64.getDecoder().decode(field(frame, "data")));
            } else if ("error".equals(type)) {
                throw new RuntimeException(field(frame, "code") + ": " + field(frame, "message"));
            }
        }

        // 44-byte WAV header: PCM, mono, 24 000 Hz, 16-bit.
        ByteBuffer h = ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN);
        h.put("RIFF".getBytes()).putInt(36 + pcm.size()).put("WAVEfmt ".getBytes())
                .putInt(16).putShort((short) 1).putShort((short) 1).putInt(24000).putInt(48000)
                .putShort((short) 2).putShort((short) 16).put("data".getBytes()).putInt(pcm.size());
        try (FileOutputStream out = new FileOutputStream("speech.wav")) {
            out.write(h.array());
            pcm.writeTo(out);
        }
    }

    // Minimal field extraction to stay dependency-free; use Jackson or Gson in real code.
    static String field(String json, String name) {
        Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*\"([^\"\\\\]*(?:\\\\.[^\"\\\\]*)*)\"").matcher(json);
        return m.find() ? m.group(1) : null;
    }

    static String number(String json, String name) {
        Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*(-?[0-9.]+)").matcher(json);
        return m.find() ? m.group(1) : null;
    }
}

// Save a stream as a WAV file. .NET 8 console app (Program.cs).
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { Timeout = Timeout.InfiniteTimeSpan }; // a stream can outlast the default 100 s
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ttswave.stream/v1/tts/stream")
{
    Content = JsonContent.Create(new { text = "Hello, and welcome to the demo. This is a short test of the speech engine." }),
};
// ResponseHeadersRead: start reading frames as they arrive instead of buffering the whole body.
using var res = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
if (!res.IsSuccessStatusCode)
    throw new Exception($"{(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");

using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());
using var pcm = new MemoryStream();
while (await reader.ReadLineAsync() is { } line)
{
    if (line.Length == 0) continue;
    using var doc = JsonDocument.Parse(line);
    var frame = doc.RootElement;
    switch (frame.GetProperty("type").GetString())
    {
        case "mark":
            Console.WriteLine($"{frame.GetProperty("startMs"),6} ms  {frame.GetProperty("text")}");
            break;
        case "audio":
            pcm.Write(frame.GetProperty("data").GetBytesFromBase64());
            break;
        case "error":
            throw new Exception($"{frame.GetProperty("code")}: {frame.GetProperty("message")}");
    }
}

// 44-byte WAV header: PCM, mono, 24 000 Hz, 16-bit.
using var wav = new BinaryWriter(File.Create("speech.wav"));
wav.Write("RIFF"u8); wav.Write(36 + (int)pcm.Length); wav.Write("WAVEfmt "u8);
wav.Write(16); wav.Write((short)1); wav.Write((short)1); wav.Write(24000); wav.Write(48000);
wav.Write((short)2); wav.Write((short)16); wav.Write("data"u8); wav.Write((int)pcm.Length);
pcm.WriteTo(wav.BaseStream);

// Plays the NDJSON relayed by YOUR backend (POST /api/speech above).
async function speak(text, { onMark } = {}) {
  const ctx = new AudioContext();
  await ctx.resume();
  const res = await fetch("/api/speech", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  if (!res.ok) throw new Error("speech failed: " + res.status);

  let playhead = 0;        // AudioContext time where the next slice starts
  let pendingMark = null;  // mark waiting for its first audio slice

  const handle = (frame) => {
    if (frame.type === "mark") {
      pendingMark = frame;
    } else if (frame.type === "audio") {
      const bin = atob(frame.data);
      const view = new DataView(Uint8Array.from(bin, (c) => c.charCodeAt(0)).buffer);
      const samples = bin.length >> 1;
      const buffer = ctx.createBuffer(1, samples, frame.sampleRate); // resampled by the browser
      const channel = buffer.getChannelData(0);
      for (let i = 0; i < samples; i++) channel[i] = view.getInt16(i * 2, true) / 32768;
      const source = ctx.createBufferSource();
      source.buffer = buffer;
      source.connect(ctx.destination);
      const when = Math.max(playhead, ctx.currentTime + 0.1); // small jitter buffer
      source.start(when);
      playhead = when + buffer.duration;
      if (pendingMark) { // fire the caption exactly when its sentence becomes audible
        const mark = pendingMark;
        pendingMark = null;
        setTimeout(() => onMark?.(mark), Math.max(0, (when - ctx.currentTime) * 1000));
      }
    } else if (frame.type === "done" && frame.browser) {
      speechSynthesis.speak(new SpeechSynthesisUtterance(text)); // your backend chose the fallback
    } else if (frame.type === "error") {
      console.error(frame.code, frame.message);
    }
  };

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buf = "";
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    let nl;
    while ((nl = buf.indexOf("\n")) >= 0) {
      const line = buf.slice(0, nl).trim();
      buf = buf.slice(nl + 1);
      if (line) handle(JSON.parse(line));
    }
  }
}

document.querySelector("#play").addEventListener("click", () =>
  speak("Hello, and welcome. This sentence is streamed.", {
    onMark: (m) => console.log("now saying:", m.text),
  })
);

BODY='{"texts": ["Welcome back to the weekly summary.", "Here are the three things that changed."], "voice": "uk-female-emma"}'

curl https://api.ttswave.stream/v1/tts/prefetch \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" -H "Content-Type: application/json" -d "$BODY"
# {"queued":2,"pending":2,"realtime":true}

curl https://api.ttswave.stream/v1/tts/status \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" -H "Content-Type: application/json" -d "$BODY"
# {"voice":"uk-female-emma","total":2,"ready":0,"queued":2,"failed":0,"complete":false,"realtime":true}
# repeat every few seconds until "complete":true (here "ready":2)

const API = "https://api.ttswave.stream";
const headers = {
  Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}`,
  "Content-Type": "application/json",
};
const body = JSON.stringify({
  texts: ["Welcome back to the weekly summary.", "Here are the three things that changed."],
  voice: "uk-female-emma",
});
const post = (path) => fetch(API + path, { method: "POST", headers, body });

// 1. Queue the text (202, returns immediately).
await post("/v1/tts/prefetch");

// 2. Poll until every sentence is cached (costs no characters).
const deadline = Date.now() + 30 * 60_000;
for (;;) {
  const st = await (await post("/v1/tts/status")).json();
  console.log(`ready ${st.ready}/${st.total}`);
  if (st.complete) break;
  if (Date.now() > deadline) throw new Error("audio still not ready");
  await new Promise((r) => setTimeout(r, 3000));
}
// 3. Stream the same texts with the same voice and speed: playback starts instantly.

import os
import time

import requests

API = "https://api.ttswave.stream"
H = {"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"}
body = {
    "texts": ["Welcome back to the weekly summary.", "Here are the three things that changed."],
    "voice": "uk-female-emma",
}

requests.post(f"{API}/v1/tts/prefetch", headers=H, json=body, timeout=30).raise_for_status()

deadline = time.time() + 30 * 60
while True:
    st = requests.post(f"{API}/v1/tts/status", headers=H, json=body, timeout=30).json()
    print(f"ready {st['ready']}/{st['total']}")
    if st["complete"]:
        break
    if time.time() > deadline:
        raise TimeoutError("audio still not ready")
    time.sleep(3)

<?php
$body = json_encode([
    "texts" => ["Welcome back to the weekly summary.", "Here are the three things that changed."],
    "voice" => "uk-female-emma",
]);

function post(string $path, string $body): array
{
    $ch = curl_init("https://api.ttswave.stream" . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("TTSWAVE_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
    ]);
    $data = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($status >= 400 || $status === 0) {
        throw new RuntimeException($data["error"]["code"] ?? curl_error($ch));
    }
    return $data;
}

// 1. Queue the text (202, returns immediately).
post("/v1/tts/prefetch", $body);

// 2. Poll until every sentence is cached (costs no characters).
$deadline = time() + 30 * 60;
while (true) {
    $st = post("/v1/tts/status", $body);
    echo "ready {$st['ready']}/{$st['total']}\n";
    if ($st["complete"]) {
        break;
    }
    if (time() > $deadline) {
        throw new RuntimeException("audio still not ready");
    }
    sleep(3);
}
// 3. Stream the same texts with the same voice and speed: playback starts instantly.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

var body, _ = json.Marshal(map[string]any{
	"texts": []string{"Welcome back to the weekly summary.", "Here are the three things that changed."},
	"voice": "uk-female-emma",
})

func post(path string, out any) {
	req, _ := http.NewRequest("POST", "https://api.ttswave.stream"+path, bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := (&http.Client{Timeout: 30 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 400 {
		log.Fatalf("%s: %s", path, res.Status)
	}
	if err := json.NewDecoder(res.Body).Decode(out); err != nil {
		log.Fatal(err)
	}
}

func main() {
	// 1. Queue the text (202, returns immediately).
	var queued struct{ Queued, Pending int }
	post("/v1/tts/prefetch", &queued)

	// 2. Poll until every sentence is cached (costs no characters).
	deadline := time.Now().Add(30 * time.Minute)
	for {
		var st struct {
			Ready, Total int
			Complete     bool
		}
		post("/v1/tts/status", &st)
		fmt.Printf("ready %d/%d\n", st.Ready, st.Total)
		if st.Complete {
			break
		}
		if time.Now().After(deadline) {
			log.Fatal("audio still not ready")
		}
		time.Sleep(3 * time.Second)
	}
	// 3. Stream the same texts with the same voice and speed: playback starts instantly.
}

// Java 11+. Save as Prefetch.java, run: java Prefetch.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Prefetch {
    static final HttpClient HTTP = HttpClient.newHttpClient();
    static final String BODY = "{\"texts\": [\"Welcome back to the weekly summary.\", "
            + "\"Here are the three things that changed.\"], \"voice\": \"uk-female-emma\"}";

    static String post(String path) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream" + path))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(30))
                .POST(HttpRequest.BodyPublishers.ofString(BODY))
                .build();
        HttpResponse<String> res = HTTP.send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) throw new RuntimeException(res.statusCode() + " " + res.body());
        return res.body();
    }

    public static void main(String[] args) throws Exception {
        // 1. Queue the text (202, returns immediately).
        post("/v1/tts/prefetch");

        // 2. Poll until every sentence is cached (costs no characters).
        long deadline = System.currentTimeMillis() + 30 * 60_000;
        while (true) {
            String st = post("/v1/tts/status"); // {"voice":"...","total":2,"ready":2,...,"complete":true,...}
            System.out.println("ready " + st.replaceAll(".*\"ready\":(\\d+).*", "$1")
                    + "/" + st.replaceAll(".*\"total\":(\\d+).*", "$1"));
            if (st.contains("\"complete\":true")) break;
            if (System.currentTimeMillis() > deadline) throw new RuntimeException("audio still not ready");
            Thread.sleep(3000);
        }
        // 3. Stream the same texts with the same voice and speed: playback starts instantly.
    }
}

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.ttswave.stream") };
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));
var body = new
{
    texts = new[] { "Welcome back to the weekly summary.", "Here are the three things that changed." },
    voice = "uk-female-emma",
};

// 1. Queue the text (202, returns immediately).
(await http.PostAsJsonAsync("/v1/tts/prefetch", body)).EnsureSuccessStatusCode();

// 2. Poll until every sentence is cached (costs no characters).
var deadline = DateTime.UtcNow.AddMinutes(30);
while (true)
{
    using var res = await http.PostAsJsonAsync("/v1/tts/status", body);
    res.EnsureSuccessStatusCode();
    var st = await res.Content.ReadFromJsonAsync<JsonElement>();
    Console.WriteLine($"ready {st.GetProperty("ready")}/{st.GetProperty("total")}");
    if (st.GetProperty("complete").GetBoolean()) break;
    if (DateTime.UtcNow > deadline) throw new TimeoutException("audio still not ready");
    await Task.Delay(3000);
}
// 3. Stream the same texts with the same voice and speed: playback starts instantly.

{
  "audioContent": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4...",
  "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000, "speakingRate": 1.0}
}

curl -sS https://api.ttswave.stream/v1/text:synthesize \
  -H "X-Goog-Api-Key: $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Hello from TTSWave."},
       "voice": {"languageCode": "en-GB", "ssmlGender": "FEMALE"},
       "audioConfig": {"audioEncoding": "MP3"}}' \
  | jq -r .audioContent | base64 -d > hello.mp3

import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.ttswave.stream/v1/text:synthesize", {
  method: "POST",
  headers: { "X-Goog-Api-Key": process.env.TTSWAVE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    input: { text: "Hello from TTSWave." },
    voice: { languageCode: "en-GB", ssmlGender: "FEMALE" },
    audioConfig: { audioEncoding: "MP3" },
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const { audioContent } = await res.json();
await writeFile("hello.mp3", Buffer.from(audioContent, "base64"));

import base64
import os

import requests

r = requests.post(
    "https://api.ttswave.stream/v1/text:synthesize",
    headers={"X-Goog-Api-Key": os.environ["TTSWAVE_API_KEY"]},
    json={
        "input": {"text": "Hello from TTSWave."},
        "voice": {"languageCode": "en-GB", "ssmlGender": "FEMALE"},
        "audioConfig": {"audioEncoding": "MP3"},
    },
    timeout=60,
)
r.raise_for_status()
with open("hello.mp3", "wb") as f:
    f.write(base64.b64decode(r.json()["audioContent"]))

<?php
$ch = curl_init("https://api.ttswave.stream/v1/text:synthesize");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Goog-Api-Key: " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "input" => ["text" => "Hello from TTSWave."],
        "voice" => ["languageCode" => "en-GB", "ssmlGender" => "FEMALE"],
        "audioConfig" => ["audioEncoding" => "MP3"],
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    throw new RuntimeException($data["error"]["code"] ?? curl_error($ch));
}
file_put_contents("hello.mp3", base64_decode($data["audioContent"]));

package main

import (
	"bytes"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"input":       map[string]string{"text": "Hello from TTSWave."},
		"voice":       map[string]string{"languageCode": "en-GB", "ssmlGender": "FEMALE"},
		"audioConfig": map[string]string{"audioEncoding": "MP3"},
	})
	req, _ := http.NewRequest("POST", "https://api.ttswave.stream/v1/text:synthesize", bytes.NewReader(body))
	req.Header.Set("X-Goog-Api-Key", os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		log.Fatalf("%s: %s", res.Status, msg)
	}
	var out struct {
		AudioContent []byte `json:"audioContent"` // base64, decoded automatically
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("hello.mp3", out.AudioContent, 0o644); err != nil {
		log.Fatal(err)
	}
}

// Java 11+. Save as Synthesize.java, run: java Synthesize.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Base64;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Synthesize {
    public static void main(String[] args) throws Exception {
        String json = "{\"input\": {\"text\": \"Hello from TTSWave.\"},"
                + " \"voice\": {\"languageCode\": \"en-GB\", \"ssmlGender\": \"FEMALE\"},"
                + " \"audioConfig\": {\"audioEncoding\": \"MP3\"}}";
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/text:synthesize"))
                .header("X-Goog-Api-Key", System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(60))
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 200) throw new RuntimeException(res.statusCode() + " " + res.body());

        Matcher audio = Pattern.compile("\"audioContent\"\\s*:\\s*\"([^\"]+)\"").matcher(res.body());
        if (!audio.find()) throw new IllegalStateException("no audioContent in response");
        Files.write(Path.of("hello.mp3"), Base64.getDecoder().decode(audio.group(1)));
    }
}

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Add("X-Goog-Api-Key", Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var res = await http.PostAsJsonAsync("https://api.ttswave.stream/v1/text:synthesize", new
{
    input = new { text = "Hello from TTSWave." },
    voice = new { languageCode = "en-GB", ssmlGender = "FEMALE" },
    audioConfig = new { audioEncoding = "MP3" },
});
var json = await res.Content.ReadFromJsonAsync<JsonElement>();
if (!res.IsSuccessStatusCode)
    throw new Exception($"{json.GetProperty("error").GetProperty("code")}: {json.GetProperty("error").GetProperty("message")}");
await File.WriteAllBytesAsync("hello.mp3", json.GetProperty("audioContent").GetBytesFromBase64());

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"inlineData": {"mimeType": "audio/L16;codec=pcm;rate=24000", "data": "AAAEAAgA..."}}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {"promptTokenCount": 9, "candidatesTokenCount": 60, "totalTokenCount": 69,
                    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 9}],
                    "candidatesTokensDetails": [{"modality": "AUDIO", "tokenCount": 60}]},
  "modelVersion": "gemini-2.5-flash-preview-tts",
  "responseId": "5d0c1f7e9a2b4c6d8e0f1a"
}

curl -sS "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
  -H "X-Goog-Api-Key: $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "Have a wonderful day!"}]}],
       "generationConfig": {"responseModalities": ["AUDIO"],
         "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}}}}' \
  | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 -d > out.pcm
ffmpeg -f s16le -ar 24000 -ac 1 -i out.pcm out.wav

import { writeFile } from "node:fs/promises";

const res = await fetch(
  "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent",
  {
    method: "POST",
    headers: { "X-Goog-Api-Key": process.env.TTSWAVE_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: "Have a wonderful day!" }] }],
      generationConfig: {
        responseModalities: ["AUDIO"],
        speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } },
      },
    }),
  }
);
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const data = await res.json();
const pcm = Buffer.from(data.candidates[0].content.parts[0].inlineData.data, "base64");

// Wrap the raw PCM in a 44-byte WAV header (24 kHz, mono, 16-bit).
const header = Buffer.alloc(44);
header.write("RIFF", 0); header.writeUInt32LE(36 + pcm.length, 4); header.write("WAVE", 8);
header.write("fmt ", 12); header.writeUInt32LE(16, 16); header.writeUInt16LE(1, 20);
header.writeUInt16LE(1, 22); header.writeUInt32LE(24000, 24); header.writeUInt32LE(48000, 28);
header.writeUInt16LE(2, 32); header.writeUInt16LE(16, 34);
header.write("data", 36); header.writeUInt32LE(pcm.length, 40);
await writeFile("out.wav", Buffer.concat([header, pcm]));

import base64
import os
import wave

import requests

r = requests.post(
    "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent",
    headers={"X-Goog-Api-Key": os.environ["TTSWAVE_API_KEY"]},
    json={
        "contents": [{"parts": [{"text": "Have a wonderful day!"}]}],
        "generationConfig": {
            "responseModalities": ["AUDIO"],
            "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}},
        },
    },
    timeout=60,
)
r.raise_for_status()
pcm = base64.b64decode(r.json()["candidates"][0]["content"]["parts"][0]["inlineData"]["data"])
with wave.open("out.wav", "wb") as wf:
    wf.setnchannels(1)
    wf.setsampwidth(2)
    wf.setframerate(24000)
    wf.writeframes(pcm)

<?php
$ch = curl_init("https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Goog-Api-Key: " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "contents" => [["parts" => [["text" => "Have a wonderful day!"]]]],
        "generationConfig" => [
            "responseModalities" => ["AUDIO"],
            "speechConfig" => ["voiceConfig" => ["prebuiltVoiceConfig" => ["voiceName" => "Kore"]]],
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    throw new RuntimeException($data["error"]["code"] ?? curl_error($ch));
}
$pcm = base64_decode($data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]);

// Wrap the raw PCM in a 44-byte WAV header (24 kHz, mono, 16-bit).
$header = pack("A4VA4A4VvvVVvvA4V", "RIFF", 36 + strlen($pcm), "WAVE", "fmt ",
    16, 1, 1, 24000, 48000, 2, 16, "data", strlen($pcm));
file_put_contents("out.wav", $header . $pcm);

package main

import (
	"encoding/binary"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

func main() {
	body := strings.NewReader(`{
		"contents": [{"parts": [{"text": "Have a wonderful day!"}]}],
		"generationConfig": {"responseModalities": ["AUDIO"],
			"speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}}}}`)
	req, _ := http.NewRequest("POST",
		"https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent", body)
	req.Header.Set("X-Goog-Api-Key", os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		log.Fatalf("%s: %s", res.Status, msg)
	}
	var out struct {
		Candidates []struct {
			Content struct {
				Parts []struct {
					InlineData struct {
						Data []byte `json:"data"` // base64 PCM, decoded automatically
					} `json:"inlineData"`
				} `json:"parts"`
			} `json:"content"`
		} `json:"candidates"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	pcm := out.Candidates[0].Content.Parts[0].InlineData.Data

	// Wrap the raw PCM in a 44-byte WAV header (24 kHz, mono, 16-bit).
	h := make([]byte, 44)
	copy(h[0:], "RIFF")
	binary.LittleEndian.PutUint32(h[4:], uint32(36+len(pcm)))
	copy(h[8:], "WAVEfmt ")
	binary.LittleEndian.PutUint32(h[16:], 16)
	binary.LittleEndian.PutUint16(h[20:], 1)
	binary.LittleEndian.PutUint16(h[22:], 1)
	binary.LittleEndian.PutUint32(h[24:], 24000)
	binary.LittleEndian.PutUint32(h[28:], 48000)
	binary.LittleEndian.PutUint16(h[32:], 2)
	binary.LittleEndian.PutUint16(h[34:], 16)
	copy(h[36:], "data")
	binary.LittleEndian.PutUint32(h[40:], uint32(len(pcm)))
	if err := os.WriteFile("out.wav", append(h, pcm...), 0o644); err != nil {
		log.Fatal(err)
	}
}

// Java 11+. Save as Gemini.java, run: java Gemini.java
import java.io.FileOutputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.time.Duration;
import java.util.Base64;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Gemini {
    public static void main(String[] args) throws Exception {
        String json = "{\"contents\": [{\"parts\": [{\"text\": \"Have a wonderful day!\"}]}],"
                + " \"generationConfig\": {\"responseModalities\": [\"AUDIO\"],"
                + " \"speechConfig\": {\"voiceConfig\": {\"prebuiltVoiceConfig\": {\"voiceName\": \"Kore\"}}}}}";
        HttpRequest request = HttpRequest.newBuilder(URI.create(
                        "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent"))
                .header("X-Goog-Api-Key", System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(60))
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 200) throw new RuntimeException(res.statusCode() + " " + res.body());

        // candidates[0].content.parts[0].inlineData.data: the only "data" field in the response
        Matcher m = Pattern.compile("\"data\"\\s*:\\s*\"([^\"]+)\"").matcher(res.body());
        if (!m.find()) throw new IllegalStateException("no audio in response");
        byte[] pcm = Base64.getDecoder().decode(m.group(1));

        // Wrap the raw PCM in a 44-byte WAV header (24 kHz, mono, 16-bit).
        ByteBuffer h = ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN);
        h.put("RIFF".getBytes()).putInt(36 + pcm.length).put("WAVEfmt ".getBytes())
                .putInt(16).putShort((short) 1).putShort((short) 1).putInt(24000).putInt(48000)
                .putShort((short) 2).putShort((short) 16).put("data".getBytes()).putInt(pcm.length);
        try (FileOutputStream out = new FileOutputStream("out.wav")) {
            out.write(h.array());
            out.write(pcm);
        }
    }
}

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Add("X-Goog-Api-Key", Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var res = await http.PostAsJsonAsync(
    "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:generateContent",
    new
    {
        contents = new[] { new { parts = new[] { new { text = "Have a wonderful day!" } } } },
        generationConfig = new
        {
            responseModalities = new[] { "AUDIO" },
            speechConfig = new { voiceConfig = new { prebuiltVoiceConfig = new { voiceName = "Kore" } } },
        },
    });
var json = await res.Content.ReadFromJsonAsync<JsonElement>();
if (!res.IsSuccessStatusCode)
    throw new Exception($"{json.GetProperty("error").GetProperty("code")}: {json.GetProperty("error").GetProperty("message")}");
byte[] pcm = json.GetProperty("candidates")[0].GetProperty("content").GetProperty("parts")[0]
    .GetProperty("inlineData").GetProperty("data").GetBytesFromBase64();

// Wrap the raw PCM in a 44-byte WAV header (24 kHz, mono, 16-bit).
using var wav = new BinaryWriter(File.Create("out.wav"));
wav.Write("RIFF"u8); wav.Write(36 + pcm.Length); wav.Write("WAVEfmt "u8);
wav.Write(16); wav.Write((short)1); wav.Write((short)1); wav.Write(24000); wav.Write(48000);
wav.Write((short)2); wav.Write((short)16); wav.Write("data"u8); wav.Write(pcm.Length);
wav.Write(pcm);

curl -sSN "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse" \
  -H "X-Goog-Api-Key: $TTSWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "This is the first sentence of the streamed reply. And here is a second sentence that follows it."}]}],
       "generationConfig": {"responseModalities": ["AUDIO"],
         "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Puck"}}}}}'

const res = await fetch(
  "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse",
  {
    method: "POST",
    headers: { "X-Goog-Api-Key": process.env.TTSWAVE_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: "This is the first sentence of the streamed reply. And here is a second sentence that follows it." }] }],
      generationConfig: {
        responseModalities: ["AUDIO"],
        speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Puck" } } },
      },
    }),
  }
);
if (!res.ok) throw new Error((await res.json()).error.code);
const decoder = new TextDecoder();
let buffer = "";
for await (const bytes of res.body) {
  buffer += decoder.decode(bytes, { stream: true }).replace(/\r/g, "");
  let end;
  while ((end = buffer.indexOf("\n\n")) !== -1) { // events end with a blank line
    const event = buffer.slice(0, end);
    buffer = buffer.slice(end + 2);
    if (!event.startsWith("data: ")) continue;
    const chunk = JSON.parse(event.slice(6));
    if (chunk.error) throw new Error(chunk.error.code);
    for (const part of chunk.candidates[0].content.parts) {
      const pcm = Buffer.from(part.inlineData.data, "base64"); // play or forward this piece
    }
  }
}

import base64
import json
import os

import requests

with requests.post(
    "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent",
    params={"alt": "sse"},
    headers={"X-Goog-Api-Key": os.environ["TTSWAVE_API_KEY"]},
    json={
        "contents": [{"parts": [{"text": "This is the first sentence of the streamed reply. And here is a second sentence that follows it."}]}],
        "generationConfig": {
            "responseModalities": ["AUDIO"],
            "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Puck"}}},
        },
    },
    stream=True,
    timeout=60,
) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        chunk = json.loads(line[6:])
        if "error" in chunk:
            raise RuntimeError(chunk["error"]["code"])
        for part in chunk["candidates"][0]["content"]["parts"]:
            pcm = base64.b64decode(part["inlineData"]["data"])  # play or forward this piece

<?php
$buffer = "";    // bytes received but not yet split into lines
$failure = null; // error event, if synthesis fails mid-stream

$ch = curl_init("https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Goog-Api-Key: " . getenv("TTSWAVE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "contents" => [["parts" => [["text" => "This is the first sentence of the streamed reply. And here is a second sentence that follows it."]]]],
        "generationConfig" => [
            "responseModalities" => ["AUDIO"],
            "speechConfig" => ["voiceConfig" => ["prebuiltVoiceConfig" => ["voiceName" => "Puck"]]],
        ],
    ]),
    CURLOPT_TIMEOUT => 60,
    // Called for every chunk as it arrives: handle each complete "data: {json}" line.
    CURLOPT_WRITEFUNCTION => function ($ch, string $bytes) use (&$buffer, &$failure) {
        $buffer .= $bytes;
        if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
            return strlen($bytes); // an error envelope, handled below
        }
        while (($nl = strpos($buffer, "\n")) !== false) {
            $line = rtrim(substr($buffer, 0, $nl), "\r");
            $buffer = substr($buffer, $nl + 1);
            if (!str_starts_with($line, "data: ")) {
                continue;
            }
            $chunk = json_decode(substr($line, 6), true);
            if (isset($chunk["error"])) {
                $failure = $chunk["error"]["code"];
                return 0; // stop the transfer
            }
            foreach ($chunk["candidates"][0]["content"]["parts"] as $part) {
                $pcm = base64_decode($part["inlineData"]["data"]); // play or forward this piece
                echo strlen($pcm), " bytes of audio\n";
            }
        }
        return strlen($bytes);
    },
]);
$ok = curl_exec($ch);
if ($failure !== null) {
    throw new RuntimeException($failure);
}
if ($ok === false) {
    throw new RuntimeException(curl_error($ch));
}
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    throw new RuntimeException(json_decode($buffer, true)["error"]["code"]);
}

package main

import (
	"bufio"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

type Chunk struct {
	Candidates []struct {
		Content struct {
			Parts []struct {
				InlineData struct {
					Data []byte `json:"data"` // base64 PCM, decoded automatically
				} `json:"inlineData"`
			} `json:"parts"`
		} `json:"content"`
	} `json:"candidates"`
	Error *struct {
		Code string `json:"code"`
	} `json:"error"`
}

func main() {
	body := strings.NewReader(`{
		"contents": [{"parts": [{"text": "This is the first sentence of the streamed reply. And here is a second sentence that follows it."}]}],
		"generationConfig": {"responseModalities": ["AUDIO"],
			"speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Puck"}}}}}`)
	req, _ := http.NewRequest("POST",
		"https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse", body)
	req.Header.Set("X-Goog-Api-Key", os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		log.Fatalf("%s: %s", res.Status, msg)
	}

	reader := bufio.NewReader(res.Body) // no line-length limit, unlike bufio.Scanner
	for {
		line, err := reader.ReadString('\n')
		if data, ok := strings.CutPrefix(strings.TrimRight(line, "\r\n"), "data: "); ok {
			var chunk Chunk
			if err := json.Unmarshal([]byte(data), &chunk); err != nil {
				log.Fatal(err)
			}
			if chunk.Error != nil {
				log.Fatal(chunk.Error.Code)
			}
			for _, part := range chunk.Candidates[0].Content.Parts {
				pcm := part.InlineData.Data // play or forward this piece
				fmt.Println(len(pcm), "bytes of audio")
			}
		}
		if err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}
	}
}

// Java 11+. Save as GeminiStream.java, run: java GeminiStream.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
import java.util.Iterator;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class GeminiStream {
    public static void main(String[] args) throws Exception {
        String json = "{\"contents\": [{\"parts\": [{\"text\": \"This is the first sentence of the streamed reply. And here is a second sentence that follows it.\"}]}],"
                + " \"generationConfig\": {\"responseModalities\": [\"AUDIO\"],"
                + " \"speechConfig\": {\"voiceConfig\": {\"prebuiltVoiceConfig\": {\"voiceName\": \"Puck\"}}}}}";
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1beta/models/"
                        + "gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse"))
                .header("X-Goog-Api-Key", System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<Stream<String>> res =
                HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofLines());
        if (res.statusCode() != 200) {
            throw new RuntimeException(res.statusCode() + " " + res.body().collect(Collectors.joining()));
        }

        Pattern data = Pattern.compile("\"data\"\\s*:\\s*\"([^\"]+)\"");
        for (Iterator<String> lines = res.body().iterator(); lines.hasNext(); ) {
            String line = lines.next();
            if (!line.startsWith("data: ")) continue;       // one "data: {json}" line per chunk
            if (line.startsWith("data: {\"error\"")) throw new RuntimeException(line.substring(6));
            Matcher m = data.matcher(line);
            while (m.find()) {
                byte[] pcm = Base64.getDecoder().decode(m.group(1)); // play or forward this piece
                System.out.println(pcm.length + " bytes of audio");
            }
        }
    }
}

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Goog-Api-Key", Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post,
    "https://api.ttswave.stream/v1beta/models/gemini-2.5-flash-preview-tts:streamGenerateContent?alt=sse")
{
    Content = JsonContent.Create(new
    {
        contents = new[] { new { parts = new[] { new { text = "This is the first sentence of the streamed reply. And here is a second sentence that follows it." } } } },
        generationConfig = new
        {
            responseModalities = new[] { "AUDIO" },
            speechConfig = new { voiceConfig = new { prebuiltVoiceConfig = new { voiceName = "Puck" } } },
        },
    }),
};
using var res = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
if (!res.IsSuccessStatusCode)
    throw new Exception($"{(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");

using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());
while (await reader.ReadLineAsync() is { } line)
{
    if (!line.StartsWith("data: ")) continue; // one "data: {json}" line per chunk
    using var doc = JsonDocument.Parse(line[6..]);
    var chunk = doc.RootElement;
    if (chunk.TryGetProperty("error", out var error))
        throw new Exception(error.GetProperty("code").GetString());
    foreach (var part in chunk.GetProperty("candidates")[0].GetProperty("content").GetProperty("parts").EnumerateArray())
    {
        byte[] pcm = part.GetProperty("inlineData").GetProperty("data").GetBytesFromBase64(); // play or forward this piece
        Console.WriteLine($"{pcm.Length} bytes of audio");
    }
}

curl https://api.ttswave.stream/v1/audio/transcriptions \
  -H "Authorization: Bearer $TTSWAVE_API_KEY" \
  -F file=@question.webm \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word"

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("question.webm")]), "question.webm");
form.append("response_format", "json");

const res = await fetch("https://api.ttswave.stream/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TTSWAVE_API_KEY}` }, // fetch sets the multipart Content-Type
  body: form,
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
console.log((await res.json()).text);

import os

import requests

with open("question.webm", "rb") as f:
    r = requests.post(
        "https://api.ttswave.stream/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.environ['TTSWAVE_API_KEY']}"},
        files={"file": ("question.webm", f)},
        data={"response_format": "verbose_json", "timestamp_granularities[]": "word"},
        timeout=120,
    )
r.raise_for_status()
result = r.json()
print(result["text"])
for w in result.get("words", []):
    print(f"{w['start']:6.2f}-{w['end']:6.2f}  {w['word']}")

<?php
$ch = curl_init("https://api.ttswave.stream/v1/audio/transcriptions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("TTSWAVE_API_KEY")],
    // An array body makes curl send multipart/form-data.
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("question.webm"),
        "response_format" => "verbose_json",
        "timestamp_granularities[]" => "word",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
]);
$result = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
    throw new RuntimeException($result["error"]["code"] ?? curl_error($ch));
}
echo $result["text"], "\n";
foreach ($result["words"] ?? [] as $w) {
    printf("%6.2f-%6.2f  %s\n", $w["start"], $w["end"], $w["word"]);
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"mime/multipart"
	"net/http"
	"os"
	"time"
)

func main() {
	// Build the multipart/form-data body.
	var body bytes.Buffer
	form := multipart.NewWriter(&body)
	audio, err := os.Open("question.webm")
	if err != nil {
		log.Fatal(err)
	}
	part, _ := form.CreateFormFile("file", "question.webm")
	io.Copy(part, audio)
	audio.Close()
	form.WriteField("response_format", "verbose_json")
	form.WriteField("timestamp_granularities[]", "word")
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.ttswave.stream/v1/audio/transcriptions", &body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TTSWAVE_API_KEY"))
	req.Header.Set("Content-Type", form.FormDataContentType())

	res, err := (&http.Client{Timeout: 120 * time.Second}).Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		log.Fatalf("%s: %s", res.Status, msg)
	}
	var result struct {
		Text  string `json:"text"`
		Words []struct {
			Start float64 `json:"start"`
			End   float64 `json:"end"`
			Word  string  `json:"word"`
		} `json:"words"`
	}
	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Text)
	for _, w := range result.Words {
		fmt.Printf("%6.2f-%6.2f  %s\n", w.Start, w.End, w.Word)
	}
}

// Java 11+. Save as Transcribe.java, run: java Transcribe.java
import java.io.ByteArrayOutputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.UUID;

public class Transcribe {
    public static void main(String[] args) throws Exception {
        // Build the multipart/form-data body by hand (HttpClient has no form helper).
        String boundary = "----ttswave" + UUID.randomUUID();
        ByteArrayOutputStream body = new ByteArrayOutputStream();
        body.write(("--" + boundary + "\r\n"
                + "Content-Disposition: form-data; name=\"response_format\"\r\n\r\n"
                + "text\r\n" // plain-text transcript; use verbose_json for timings
                + "--" + boundary + "\r\n"
                + "Content-Disposition: form-data; name=\"file\"; filename=\"question.webm\"\r\n"
                + "Content-Type: application/octet-stream\r\n\r\n").getBytes(StandardCharsets.UTF_8));
        body.write(Files.readAllBytes(Path.of("question.webm")));
        body.write(("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ttswave.stream/v1/audio/transcriptions"))
                .header("Authorization", "Bearer " + System.getenv("TTSWAVE_API_KEY"))
                .header("Content-Type", "multipart/form-data; boundary=" + boundary)
                .timeout(Duration.ofSeconds(120))
                .POST(HttpRequest.BodyPublishers.ofByteArray(body.toByteArray()))
                .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 200) throw new RuntimeException(res.statusCode() + " " + res.body());
        System.out.println(res.body().trim());
    }
}

using System.Text.Json;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + Environment.GetEnvironmentVariable("TTSWAVE_API_KEY"));

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(await File.ReadAllBytesAsync("question.webm")), "file", "question.webm" },
    { new StringContent("verbose_json"), "response_format" },
    { new StringContent("word"), "timestamp_granularities[]" },
};
using var res = await http.PostAsync("https://api.ttswave.stream/v1/audio/transcriptions", form);
using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
if (!res.IsSuccessStatusCode)
    throw new Exception($"{doc.RootElement.GetProperty("error").GetProperty("code")}");

Console.WriteLine(doc.RootElement.GetProperty("text"));
if (doc.RootElement.TryGetProperty("words", out var words))
{
    foreach (var w in words.EnumerateArray())
        Console.WriteLine($"{w.GetProperty("start").GetDouble(),6:F2}-{w.GetProperty("end").GetDouble(),6:F2}  {w.GetProperty("word")}");
}

{
  "text": "What time does the store open tomorrow?",
  "language": "en",
  "duration": 2.61,
  "segments": [
    {"start": 0.0, "end": 2.4, "text": "What time does the store open tomorrow?",
     "words": [{"start": 0.0, "end": 0.18, "word": "What", "probability": 0.98}]}
  ],
  "processingMs": 540,
  "words": [{"start": 0.0, "end": 0.18, "word": "What", "probability": 0.98}]
}

curl https://api.ttswave.stream/v1/info -H "Authorization: Bearer $TTSWAVE_API_KEY"

{
  "service": "TTSWave",
  "version": "1.4.0",
  "provider": "local-kokoro",
  "model": "kokoro-v1.0.onnx",
  "sampleRate": 24000,
  "defaultVoice": "us-female-heart",
  "maxConcurrent": 1,
  "stt": {"enabled": true, "model": "base.en", "device": "cpu", "compute_type": "int8", "loaded": true},
  "engines": {
    "kokoro": {"available": true, "realtime": true},
    "yarngpt": {"available": false, "configured": false, "queue": 0, "realtime": false, "status": "disabled"}
  }
}

curl https://api.ttswave.stream/healthz
# {"status":"ok"}

{"error": {"code": "voice_not_ready", "status": 409, "ready": 3, "total": 12,
           "message": "Voice ... is not realtime and 9 of 12 sentences are not generated yet; they have been queued. Poll POST /v1/tts/status and retry when complete"}}

// Plays parts back to back on one AudioContext timeline, with no timers.
// Your backend relays POST /v1/tts/stream (/api/speech) and POST /v1/tts/prefetch (/api/prefetch).
const post = (url, body, signal) => fetch(url, { method: "POST", signal,
  headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });

async function playParts(parts, { voice } = {}) {
  const ctx = new AudioContext();          // create it in the click handler
  await ctx.resume();
  post("/api/prefetch", { texts: parts, voice });   // best: everything, once, in order
  let playhead = 0;                        // AudioContext time where the next frame starts

  // Streams one part, schedules every frame on the shared playhead,
  // and returns a promise that resolves when that part has finished playing.
  async function streamPart(text) {
    const res = await post("/api/speech", { text, voice });
    if (!res.ok) throw new Error("speech " + res.status);   // 409 / 429 / 503: fall back
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buf = "", last = null;
    for (;;) {
      const { value, done } = await reader.read();  // keeps running in background tabs
      if (done) break;
      buf += decoder.decode(value, { stream: true });
      let nl;
      while ((nl = buf.indexOf("\n")) >= 0) {
        const line = buf.slice(0, nl).trim();
        buf = buf.slice(nl + 1);
        if (!line) continue;
        const frame = JSON.parse(line);
        if (frame.type === "error") throw new Error(frame.code);
        if (frame.type !== "audio") continue;
        const bin = atob(frame.data);
        const view = new DataView(Uint8Array.from(bin, (c) => c.charCodeAt(0)).buffer);
        const buffer = ctx.createBuffer(1, bin.length >> 1, frame.sampleRate);
        const ch = buffer.getChannelData(0);
        for (let i = 0; i < ch.length; i++) ch[i] = view.getInt16(i * 2, true) / 32768;
        last = ctx.createBufferSource();
        last.buffer = buffer;
        last.connect(ctx.destination);
        const when = Math.max(playhead, ctx.currentTime + 0.05);
        last.start(when);
        playhead = when + buffer.duration;
      }
    }
    return last ? new Promise((r) => last.addEventListener("ended", r)) : Promise.resolve();
  }

  // Part n+1 is fetched while part n plays; never more than two parts are buffered.
  let olderEnded = Promise.resolve(), prevEnded = Promise.resolve();
  for (const text of parts) {
    await olderEnded;                      // the part before the one playing now is over
    const ended = await streamPart(text);
    [olderEnded, prevEnded] = [prevEnded, ended];
  }
  await prevEnded;
}

# pip install openai
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttswave.stream/v1", api_key=os.environ["TTSWAVE_API_KEY"])

# Text to speech
speech = client.audio.speech.create(
    model="tts-1",               # ignored
    voice="us-female-heart",     # a TTSWave voice id
    input="Hello from TTSWave.",
    response_format="mp3",
)
speech.write_to_file("hello.mp3")

# Speech to text (if enabled on the server)
with open("question.webm", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",       # ignored
        file=f,
        response_format="verbose_json",
        timestamp_granularities=["word"],
    )
print(result.text)

// npm install openai
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.ttswave.stream/v1", apiKey: process.env.TTSWAVE_API_KEY });

// Text to speech
const speech = await client.audio.speech.create({
  model: "tts-1",            // ignored
  voice: "us-female-heart",  // TypeScript: add `as any`, the typings list OpenAI voice names only
  input: "Hello from TTSWave.",
  response_format: "mp3",
});
fs.writeFileSync("hello.mp3", Buffer.from(await speech.arrayBuffer()));

// Speech to text (if enabled on the server)
const transcript = await client.audio.transcriptions.create({
  model: "whisper-1",        // ignored
  file: fs.createReadStream("question.webm"),
});
console.log(transcript.text);

import os
import wave

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["TTSWAVE_API_KEY"],
    http_options=types.HttpOptions(base_url="https://api.ttswave.stream"),
)
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-tts",
    contents="Have a wonderful day!",
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO"],
        speech_config=types.SpeechConfig(
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore"),
            )
        ),
    ),
)
pcm = response.candidates[0].content.parts[0].inline_data.data  # bytes: 24 kHz mono 16-bit PCM
with wave.open("out.wav", "wb") as wf:
    wf.setnchannels(1)
    wf.setsampwidth(2)
    wf.setframerate(24000)
    wf.writeframes(pcm)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.TTSWAVE_API_KEY,
  httpOptions: { baseUrl: "https://api.ttswave.stream" },
});
const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-preview-tts",
  contents: [{ parts: [{ text: "Have a wonderful day!" }] }],
  config: {
    responseModalities: ["AUDIO"],
    speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } },
  },
});
const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data; // base64 PCM
const pcm = Buffer.from(data, "base64");

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

{"error": {"code": "rate_limited", "message": "Rate limit exceeded: 120 requests per minute for this key. Retry in 12 s", "status": 429}}

{
  "error": {
    "code": "voice_not_found",
    "message": "Unknown voice(s): us-female-nobody",
    "status": 400
  }
}

const res = await fetch(
  `https://texttospeech.googleapis.com/v1/text:synthesize?key=${process.env.GOOGLE_API_KEY}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      input: { text },
      voice: { languageCode: "en-US", name: "en-US-Neural2-F" },
      audioConfig: { audioEncoding: "MP3" },
    }),
  }
);
const { audioContent } = await res.json(); // base64 MP3

const res = await fetch("https://api.ttswave.stream/v1/text:synthesize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Goog-Api-Key": process.env.TTSWAVE_API_KEY, // header, never ?key=
  },
  body: JSON.stringify({
    input: { text },
    voice: { languageCode: "en-US", ssmlGender: "FEMALE" }, // or name: "us-female-heart"
    audioConfig: { audioEncoding: "MP3" },
  }),
});
const { audioContent } = await res.json(); // base64 MP3, same shape

const BASE = "https://generativelanguage.googleapis.com";
const res = await fetch(`${BASE}/v1beta/models/gemini-2.5-flash-preview-tts:generateContent`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-goog-api-key": process.env.GEMINI_API_KEY },
  body: JSON.stringify({
    contents: [{ parts: [{ text }] }],
    generationConfig: {
      responseModalities: ["AUDIO"],
      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } },
    },
  }),
});
const data = (await res.json()).candidates[0].content.parts[0].inlineData.data; // base64 PCM

const BASE = "https://api.ttswave.stream"; // changed
const res = await fetch(`${BASE}/v1beta/models/gemini-2.5-flash-preview-tts:generateContent`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-goog-api-key": process.env.TTSWAVE_API_KEY }, // changed
  body: JSON.stringify({
    contents: [{ parts: [{ text }] }],
    generationConfig: {
      responseModalities: ["AUDIO"],
      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }, // or "us-female-heart"
    },
  }),
});
const data = (await res.json()).candidates[0].content.parts[0].inlineData.data; // base64 PCM, same shape

async function ttswave(text) {
  const res = await fetch("https://api.ttswave.stream/v1/text:synthesize", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Goog-Api-Key": process.env.TTSWAVE_API_KEY },
    body: JSON.stringify({ input: { text }, voice: { languageCode: "en-US" }, audioConfig: { audioEncoding: "MP3" } }),
    signal: AbortSignal.timeout(15_000), // allow about the length of the audio
  });
  if (!res.ok) {
    const { error } = await res.json().catch(() => ({ error: {} }));
    throw new Error(`TTSWave ${res.status} ${error.code ?? ""}`);
  }
  return (await res.json()).audioContent;
}

// Returns { provider, audioContent } or { provider: "browser" } for on-device speech.
export async function synthesize(text) {
  try {
    return { provider: "ttswave", audioContent: await ttswave(text) };
  } catch (err) {
    console.warn("TTSWave failed, falling back:", err.message);
  }
  try {
    return { provider: "previous", audioContent: await previousProvider(text) }; // your old Google call
  } catch (err) {
    console.warn("Previous provider failed:", err.message);
  }
  return { provider: "browser" }; // frontend: speechSynthesis.speak(new SpeechSynthesisUtterance(text))
}