# Breeze TTS 2 — HTTP API guide

Text → speech on this box (NVIDIA GB10, open-weight `BreezeBlue/Breeze-TTS-2`).
One HTTP front door, two processes behind it:

```
you / browser / agent ──HTTP──▶ web layer :8388 ──HTTP──▶ engine :7860 (breeze_infer.api, unchanged)
                                 this API, web UI,          CUDA graphs, single GPU slot,
                                 WAV + history + presets    raw s16le PCM in/out
```

## 60-second version

```bash
BASE=http://147.8.181.122:8388      # or http://127.0.0.1:8388 on the box itself

curl -s $BASE/health                # {"status":"ok","sample_rate":24000}

curl -s -o ferry.wav $BASE/api/tts \
  -H 'content-type: application/json' \
  -d '{
        "text": "大家早上好，八点四十那一班船推迟了十二分钟，我们还来得及喝杯咖啡。",
        "voice": "man_zh",
        "cfg_scale": 4,
        "seed": 42
      }'
```

That is the whole happy path: JSON in, WAV out. Everything else is variation.

## Base URL, sign-in and API keys

| what | value |
|---|---|
| Web UI | `https://tts.qrhk.app/` (also `http://147.8.181.122:8388/` on the LAN) |
| API base | `https://tts.qrhk.app` (`http://127.0.0.1:8388` on the GPU box) |
| Swagger / OpenAPI | `/docs`, schema at `/openapi.json` |
| Engine (internal) | `http://127.0.0.1:7860` — the vendored server, proxied at `/v1/*` |
| Humans | sign in at `/` with your account → `breeze_session` cookie, 30 days |
| Scripts / agents | an **API key** (`breeze_…`) minted in the site's **API keys** panel |

Two doors, both accepted by `/api/*`, `/v1/*` and `/files/*`:

**Sign in (browser).** `POST /api/login {username, password}` sets an `HttpOnly`, `SameSite=Lax`,
`Secure` cookie; `GET /api/session` tells you who you are; `POST /api/logout` clears it.
Accounts are configured in `webui.env` as **scrypt hashes** (`BREEZE_WEB_USERS=user=scrypt$…`,
generate with `python3 webui/hash_password.py <user>`), so the server never stores or logs a
plaintext password. Eight wrong passwords from one address in ten minutes → `429`.

**API keys (scripts and agents).** Sign in, then top bar → **API keys** → *create key*, or:

```bash
curl -c jar.txt -X POST $BASE/api/login -H 'content-type: application/json' \
  -d '{"username":"<account>","password":"<password>"}'
curl -s -b jar.txt -X POST $BASE/api/keys -H 'content-type: application/json' \
  -d '{"label":"my agent"}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["key"])'
```

Send the key any of three equivalent ways:

```text
Authorization: Bearer breeze_…        preferred
X-API-Key: breeze_…
?key=breeze_…                         handy for <audio>/download links
```

* the key text is shown **once** at creation — only its SHA-256 is stored;
* `GET /api/keys` lists label, prefix, created and **last used**; `DELETE /api/keys/{id}`
  revokes it (dead within ~30 s, cached verifications expire);
* **an API key cannot list or create keys** — only a signed-in account can, so a leaked
  key cannot mint more of itself;
* an operator may also keep a master key in `BREEZE_WEB_API_KEY`; with neither accounts
  nor a master key configured the server is open (private LAN only);
* `/health`, `/api/info`, `/api/status`, `/api/guide`, `/api/skill` stay open so the UI
  can explain itself before you sign in.

Every example below assumes:

```bash
export BASE=https://tts.qrhk.app
export BREEZE_API_KEY=breeze_…        # site → API keys → create key (shown once)
alias bcurl='curl -s -H "Authorization: Bearer $BREEZE_API_KEY"'
```

## Three ways to make a voice

| mode | needs | `cfg_scale` | notes |
|---|---|---|---|
| **Voice design** | text + `instruction` (or a `voice` preset) | 4 | no reference audio; the description *is* the voice |
| **Voice direction** | text + reference audio + `ref_text` + `instruction` | 4 | keeps the reference speaker, steers pace / tone / emotion |
| **Voice clone** | text + reference audio + `ref_text` | 1 | timbre only, no instruction |

Rules the model actually cares about:

- **Write `instruction` in the same language as the text.** It is not translated.
  Cantonese = written Cantonese + a Cantonese instruction (there is no `accent` flag in
  the open weights — that is hosted-API only).
- **`cfg_scale` other than 1 requires an instruction.** CFG steers the instruction; with none
  the engine has no negative branch to steer away from. `/api/tts` refuses with `400`, the raw
  `/v1/audio/speech` fails deeper (`500 … does not define a negative prompt`). Plain text and
  voice clone therefore run at `cfg_scale=1`.
- **Vocal events inline**: `(laugh)` `(sigh)` `(cough)` `(clears throat)` in English,
  `[笑]` `[叹气]` `[咳嗽]` `[清嗓子]` in Chinese.
- **Same seed + same text + same instruction = same audio.** Change the seed for a take.
- `cfg_scale` 1 ignores the instruction, 4 is the sweet spot, 8+ gets stiff.
- Child and elderly voices speak much slower: same text, ~1.7× the duration.

## Endpoints

| method | path | what it gives you |
|---|---|---|
| `POST` | `/api/tts` | JSON in → **WAV/MP3 bytes** (or metadata JSON with `?respond=json`) |
| `POST` | `/api/tts/clone` | multipart, upload your own reference audio |
| `POST` | `/api/tts/batch` | many texts, one batched decode, JSON with one clip each |
| `GET` | `/api/voices` | voice-design presets |
| `POST` / `DELETE` | `/api/voices` / `/api/voices/{id}` | save / drop a custom preset |
| `GET` | `/api/history?limit=50` | clip index (SQLite) with URLs and timings |
| `GET` / `DELETE` | `/api/history/{id}` | one clip / delete clip + file |
| `GET` | `/api/samples` | example scripts, one per language |
| `POST` | `/api/login` · `/api/logout` | account sign-in (sets / clears the session cookie) |
| `GET` | `/api/session` | who am I: `{signed_in, via, user, can_manage_keys}` |
| `GET` `POST` `DELETE` | `/api/keys` · `/api/keys/{id}` | mint / list / revoke API keys (account session required) |
| `GET` | `/api/info` · `/api/status` | capabilities · live slot, queue, backend reachability |
| `GET` | `/api/guide` · `/api/skill` | this document / the agent skill, as markdown |
| `GET` | `/files/{name}` | clip audio (append `?key=` when auth is on) |
| `POST` | `/v1/audio/speech` | **raw** streaming s16le PCM (transparent proxy to the engine) |
| `POST` | `/v1/audio/speech/batch` | raw concatenated PCM, split with `X-Segment-Bytes` |
| `GET` | `/v1/model` · `/health` | checkpoint digest & limits · readiness |

### `POST /api/tts`

Request body (JSON):

| field | type | default | meaning |
|---|---|---|---|
| `text` | str | required | what to say, ≤ ~900 chars for one request |
| `voice` | str | – | preset id from `/api/voices`; fills the instruction |
| `instruction` | str | – | natural-language direction; wins over `voice` |
| `cfg_scale` | float | 4.0 | instruction adherence (0–10, exclusive of 0) |
| `seed` | int | 42 | reproducible sampling |
| `takes` | int | 1 | 1–4 alternate takes (`seed`, `seed+1`, …) |
| `format` | `wav`\|`mp3` | `wav` | delivered container (WAV is always kept on disk) |
| `name` | str | – | label stored with the clip |
| `ref_clip` | str | – | clip id to reuse as reference audio (clone / direction) |
| `ref_text` | str | `""` | **exact** transcript of that reference audio |

Query: `?respond=auto|json|audio`. `auto` = audio bytes for one take, JSON for several.

Response headers: `X-Clip-Id`, `X-Duration`, `X-Ttfa`, `X-Gen-Seconds`, `X-Sample-Rate`,
`X-Seed`, and `X-Note` when the text hit the length cap.

```bash
# one take, straight to a file
curl -s -o out.wav "$BASE/api/tts" -H 'content-type: application/json' \
  -d '{"text":"(sigh) It is good to hear your voice again.","instruction":"A tired but warm woman in her forties, speaking slowly.","cfg_scale":4}'

# three takes, JSON manifest with URLs
curl -s "$BASE/api/tts?respond=json" -H 'content-type: application/json' \
  -d '{"text":"五隻小老鼠，行路慢慢。","voice":"kid5_yue","takes":3,"seed":42}'
```

```json
{ "count": 3, "clips": [
  { "id": "1a2b3c4d5e6f", "url": "/files/1a2b3c4d5e6f.wav", "wav_url": "/files/1a2b3c4d5e6f.wav",
    "text": "五隻小老鼠，行路慢慢。", "mode": "voice_design", "voice": "kid5_yue",
    "cfg_scale": 4.0, "seed": 42, "sample_rate": 24000,
    "duration_s": 29.52, "ttfa_s": 0.24, "gen_s": 48.8, "created": 1763200000.1 } ] }
```

### `POST /api/tts/clone` (multipart)

```bash
curl -s -o me.wav "$BASE/api/tts/clone" \
  -F "text=多謝你今日嚉呢度等我。" \
  -F "ref_audio=@my_voice.wav" \
  -F "ref_text=我呢把聲其實好易認，一聽就知係我。" \
  -F "instruction=慢啲講，溫柔啲，好似同屋傾電話。" \
  -F "cfg_scale=4" -F "seed=7" -F "format=mp3"
```

Reference audio: 3–10 s of clean, non-looping speech; `ref_text` must be *exactly* what is
said in it (including repetitions).

Reuse something this server already made (pick a take you liked, then keep that voice):

```bash
CLIP=1a2b3c4d5e6f
curl -s -o next.wav "$BASE/api/tts" -H 'content-type: application/json' \
  -d "{\"text\":\"第二句。\",\"ref_clip\":\"$CLIP\",\"ref_text\":\"五隻小老鼠，行路慢慢。\",\"cfg_scale\":4}"
```

### `POST /api/tts/batch`

Many lines in one decode — much cheaper than N single requests, but it uses the eager
batch path, so **for one line `/api/tts` is faster**. Use it from ~3 lines up.

```bash
curl -s "$BASE/api/tts/batch" -H 'content-type: application/json' \
  -d '{"texts":["First stop, Central.","Second stop, Wan Chai.","Third stop, Causeway Bay."],
       "voice":"woman_en","cfg_scale":4,"name":"tram announcement"}'
```

`texts` ≤ 128 entries; `max_new_tokens` (≤ 1500) caps each line. Response:
`{"batch_id": "...", "count": N, "wall_s": 62.4, "clips": [...]}`.

### Raw streaming (`/v1/*`) — lowest latency path

Transparent proxy to the vendored engine. Mono **24 kHz signed 16-bit little-endian PCM**,
no container, chunked as it is generated. These proxies do **not** queue: while another job
runs you get `409` (that is the documented upstream contract).

```bash
curl -sN "$BASE/v1/audio/speech" \
  -F "text=Welcome aboard. Your journey begins now." \
  -F "instruction=A calm, clear narrator." -F "cfg_scale=4" -F "seed=42" \
  --output voice.pcm                     # raw PCM, headers: X-Sample-Rate, X-Sample-Format

ffplay -autoexit -f s16le -ar 24000 -ac 1 voice.pcm   # listen
ffmpeg -f s16le -ar 24000 -ac 1 -i voice.pcm voice.wav  # or wrap into a WAV

# play while it generates (first audio in ~0.25 s)
curl -sN "$BASE/v1/audio/speech" -F "text=Hello there." -F "seed=42" \
  | ffplay -nodisp -autoexit -probesize 4096 -f s16le -ar 24000 -ac 1 -
```

Batch raw form: same as upstream — `texts` is a JSON array, the body is every segment
concatenated, `X-Segment-Bytes` lists each segment's byte length.

### Python

```python
import os, wave, requests

BASE = "https://tts.qrhk.app"
HEADERS = {"Authorization": f"Bearer {os.environ['BREEZE_API_KEY']}"}

r = requests.post(f"{BASE}/api/tts", headers=HEADERS, json={
    "text": "早上好，我在码头等你们。", "voice": "man_zh", "cfg_scale": 4, "seed": 42,
}, timeout=600)
r.raise_for_status()
open("clip.wav", "wb").write(r.content)          # already a WAV, nothing to convert
```

Streaming with the standard library:

```python
import os, urllib.request, wave

key = os.environ["BREEZE_API_KEY"]
req = urllib.request.Request(
    "https://tts.qrhk.app/v1/audio/speech", data=b"text=Hello+there.&seed=42",
    headers={"content-type": "application/x-www-form-urlencoded",
             "authorization": f"Bearer {key}"})
with urllib.request.urlopen(req) as response, wave.open("out.wav", "wb") as wav:
    wav.setnchannels(1); wav.setsampwidth(2); wav.setframerate(24000)
    while chunk := response.read(8192):
        wav.writeframes(chunk)
```

> **Public URL only:** Cloudflare in front of `tts.qrhk.app` sometimes refuses
> `Python-urllib` **POSTs** with `403 error code: 1010`. `requests`, `curl` and the skill
> script work; on the LAN (`http://127.0.0.1:8388`) plain `urllib` is fine.

### Presets

```bash
curl -s $BASE/api/voices | python3 -m json.tool | head -40
```

Built-ins come from `scripts.json` (12 test characters + granny + child, in Putonghua /
English / Cantonese). Save your own:

```bash
curl -s $BASE/api/voices -H 'content-type: application/json' \
  -d '{"id":"radio_host","label":"Late night radio host","language":"zh",
       "instruction":"低沉温柔的男声，语速偏慢，像深夜电台，句尾略微下沉。"}'
```

Presets are just saved instructions — the model has no fixed speaker list.

### History

```bash
curl -s "$BASE/api/history?limit=5" | python3 -m json.tool
curl -s -X DELETE $BASE/api/history/1a2b3c4d5e6f      # removes the row and the files
```

Rows keep text, mode, preset, instruction, `ref_clip`/`ref_text`, cfg, seed, sample rate,
duration, TTFA, generation time, and the WAV/MP3 filenames, so any clip can be replayed
or re-used as a reference later. Files live in `webui/clips/` (SQLite index `clips.db`).

## Ready to run

```bash
export BASE=https://tts.qrhk.app
export BREEZE_API_KEY=breeze_…        # sign in at / → top bar “API keys” → create key
```

**Agent one-liner** (the skill script, stdlib only — see `/api/skill`):

```bash
python3 skills/breeze-tts-api/scripts/breeze_tts.py say "多謝你今日等我。" \
  --preset woman_yue --out clip.wav          # add --json for the manifest
python3 skills/breeze-tts-api/scripts/breeze_tts.py presets                 # voice ids
python3 skills/breeze-tts-api/scripts/breeze_tts.py clone me.wav \
  --ref-text "exactly what I say in that file" --text "新的一句。"
python3 skills/breeze-tts-api/scripts/breeze_tts.py stream "Hello there." \
  --instruction "A bright young woman." --play      # first audio in ~0.2 s
```

**curl**

```bash
curl -s -o greeting.wav -D headers.txt "$BASE/api/tts" \
  -H "Authorization: Bearer $BREEZE_API_KEY" -H 'content-type: application/json' \
  -d '{"text":"Hello from Breeze TTS 2 running locally.","cfg_scale":1,"seed":42}'
```

**Python**

```python
import os, requests
requests.post(os.environ.get("BREEZE_BASE", "https://tts.qrhk.app") + "/api/tts",
              headers={"Authorization": f"Bearer {os.environ['BREEZE_API_KEY']}"},
              json={"text": "Hello from the API.", "cfg_scale": 1, "seed": 42},
              timeout=600).raise_for_status()
# .content is the WAV; write it straight to a file
```

**Copy-paste map**

| I want | call |
|---|---|
| voice from a description | `POST /api/tts` + `instruction` (or `voice`) + `cfg_scale: 4` |
| copy someone's voice | `POST /api/tts/clone` multipart: `ref_audio` + exact `ref_text`, `cfg_scale: 1` |
| keep a voice, change the delivery | same, plus `instruction`, `cfg_scale: 4` |
| first audio in ~0.2 s | `POST /v1/audio/speech` (raw PCM, `-F` form fields, no queueing) |
| several lines cheaply | `POST /api/tts/batch` |
| a key for a script | sign in → `POST /api/keys` (or the **API keys** panel) |

**Gotchas**

- `cfg_scale: 4` without any instruction → clean `400`; use `cfg_scale: 1` for plain TTS and clone.
- `ref_text` that isn't *exactly* what the reference says → garbled output, not an error.
- `instruction` must be in the same language as `text`.
- more than ~900 characters → truncated to fit the 120 s window; `X-Note` / `note` says so.
- `503` = engine still warming up (70–240 s after a start), `409` = GPU busy on raw `/v1` only.
- through the public URL, prefer `curl` / `requests` over raw `urllib` POSTs (Cloudflare can
  answer `403 error code: 1010`); on the LAN everything works.

## Limits, concurrency, latency

| thing | value |
|---|---|
| output | 24 kHz mono, WAV (PCM_16) or MP3 |
| max audio per request | ~120 s (`max_new_tokens=1500` ÷ 12.5 frames/s) — longer text is cut, `X-Note`/`note` says so |
| practical text size | ≤ ~900 chars (≈ 400 CJK chars) per request |
| concurrency | **one GPU slot**; `/api/*` queues (max 16 waiting, then `429`), `/v1/*` answers `409` |
| TTFA (fast path, warmed) | **0.21–0.26 s** |
| generation speed | **RTF ≈ 1.66** → a 20 s clip takes ~33 s |
| engine warm-up | 70–240 s with CUDA graphs (`/health` returns `503` until ready) |

RTF 1.66 means this box is **not** quite 1× realtime: streaming playback starts instantly
(~0.25 s) but long text keeps running behind the playhead. Batch several lines instead of
issuing many single requests when you are generating offline.

Status codes you will actually see: `400` bad/empty text, missing `ref_text`, bad cfg ·
`404` unknown preset or clip id · `409` engine slot busy (raw `/v1` only) ·
`413` reference audio over 25 MB · `422` JSON validation (see `detail`) ·
`429` queue full · `502` engine unreachable · `503` engine still warming up.

## Ops

```bash
./breezectl status                 # both services + GPU
./breezectl logs webui             # follow the web layer
./breezectl restart-backend        # engine only (after a wedge or a config change)
tail -f webui/webui.log webui/backend.log
```

Files: `webui/server.py` (this API + UI), `webui/backend.log`, `webui/webui.log`,
`webui/clips/` (audio + `clips.db`), `webui/voices.json` (saved presets),
`webui/docs/API.md` (this page, served at `/api/guide`),
`skills/breeze-tts-api/SKILL.md` (agent skill, served at `/api/skill`).

Environment: `BREEZE_WEB_PORT` (8388) · `BREEZE_BACKEND_URL` (http://127.0.0.1:7860) ·
`BREEZE_WEB_API_KEY` (require a key) · `BREEZE_MODEL_DIR` · `BREEZE_FAST_ALL` (1) ·
`BREEZE_SPAWN_BACKEND` (1 = start the engine as a child instead of a second service).

Debug a stuck web layer without restarting: `kill -USR1 <webui pid>` dumps all Python
thread stacks into `webui/webui.log`.

## Licence

Code here is yours to keep; the **model weights and self-hosted outputs are research /
non-commercial only** (BreezeBlue Research and Non-Commercial License). Commercial rights
apply only to outputs from BreezeBlue's paid hosted API. Reference audio must be audio you
have the right to use — no impersonation.
