Blame for docs/api.md

# HTTP API

`gsv_server` exposes an api_v2-compatible subset over HTTP. The machine-readable description

is served by the server itself: `GET /docs` or `GET /openapi.json` (OpenAPI 3).



## Basics



- Default address: `http://127.0.0.1:9880` (see `--host` / `--port`).

- Auth: when started with `--token <T>`, every request must send `Authorization: Bearer <T>`

  or `?token=<T>`. Binding to a non-loopback address requires `--token`.

- File access: `ref_audio_path` must live under one of the `--allow-path` directories, or under

  the upload directory created by `POST /reference`. Otherwise the server answers `403`.

- Errors are JSON: `{"code": "<error_code>", "message": "<human readable>"}` with HTTP status

  `400` (bad request), `401` (auth), `403` (path), `500` (engine), `501` (not implemented),

  `503` (busy / sidecar down), `504` (timeout).

- Responses carry `X-Request-Id` (supply your own via the header if you want it echoed).



## POST /tts



Synthesize one text.



```json

{

  "text": "你好，欢迎使用语音合成系统。",

  "text_lang": "zh",
  "ref_audio_path": "/path/to/ref.wav",
  "prompt_text": "reference transcript",

  "prompt_lang": "zh",
  "sample_steps": 4,

  "cfg_rate": 0.0,
  "seed": 20261014,
  "stream": false
}
```



| field | type | default | notes |

|---|---|---|---|

| `text` | string | — | required, <= 4000 bytes |

| `text_lang` | string | `zh` | `zh` / `en` / `ja` / `ko` / `yue` |

| `ref_audio_path` | string | — | required unless a default reference was set |

| `prompt_text` | string | — | required unless a default reference was set |

| `prompt_lang` | string | `zh` | language of `prompt_text` |

| `voice` | string | current | registered voice name |

| `sample_steps` | int | per voice | 1..1000 (v5turbo 4, v5dev 32) |

| `cfg_rate` | float | per voice | <= 20 |

| `seed` | int | -1 | -1 = random |

| `top_k`, `top_p`, `temperature`, `repetition_penalty` | | AR defaults (15/1/1/1.35) | |

| `speed_factor` | float | 1.0 | (0, 4] |

| `text_split_method` | string | `cut5` | `cut0`..`cut5` |

| `fragment_interval` | float | 0.3 | silence between segments, seconds (0..5) |

| `dbcache` | string | `auto` | cache-dit: `off` / `auto` / `f4` / `f8` / `f16` |

| `media_type` | string | `wav` | only `wav` |

| `stream` | bool | `false` | see below |



`GET /tts` accepts the same fields as query parameters.



Non-stream response: `audio/wav`, 48 kHz mono 16-bit, whole-request peak-normalized to 0.708.



### Streaming (`stream: true`)



`POST /tts` with `stream: true` answers `Transfer-Encoding: chunked` with `audio/wav`:



- the 44-byte WAV header is sent immediately (RIFF/data sizes are `0xFFFFFFFF`, as usual for

  streaming WAV; players read until the connection closes);

- PCM is flushed after every text segment, plus `fragment_interval` of silence between segments;

- segments use a finer splitter than `cut5` (sentence-sized, >= 4 chars, <= 60 chars per chunk),

  so the first audio arrives earlier; `text_split_method=cut0` disables splitting;

- streamed audio is **not** peak-normalized (per-segment normalization would pump the volume);

- streamed requests bypass the AR batching scheduler, so total time can be higher than

  non-streaming for the same text; use streaming for latency, not throughput.



Measured on the dev box (CPU, 3 sentences): header in 13 ms, first PCM after the first segment,

total roughly the sum of the segments.



## GET /health, GET /metrics



`/health` → readiness: `{"ok":true,"engine":"ready","voice":"default","sidecar":true,"queue":0,...}`.



`/metrics` → counters: `tts_requests`, `errors`, `jobs`, `timeouts`, `busy`, `reloads`,

`ar_batches`, `ar_tasks`, `sched_batches`, `sched_texts`, `queue`, `waiters`, `last_total_ms`.



## Batch



- `POST /batch` with `{"texts":[...], ...same fields as /tts}` → `{"job_id":"<id>","total":N}`.

- `GET /jobs/<id>` → state (`queued` / `running` / `done` / `canceled` / `failed`).

- `GET /jobs/<id>/result/<i>` → WAV of item `i`.

- `DELETE /jobs/<id>` → cancel / drop.



## References



- `GET /change_refer?refer_wav_path=...&prompt_text=...&prompt_lang=zh` (POST also accepts a JSON

  body) stores a **default reference**. Later `/tts` calls may omit `ref_audio_path` /

  `prompt_text` / `prompt_lang`.

- `GET /set_refer_audio?...` is an alias of `/change_refer`.

- `POST /reference` with a raw WAV body uploads a reference to the temp directory and returns

  `{"path": "...", "bytes": N}`; that path is implicitly allowed for `ref_audio_path`.



## Misc



- `GET /models` → voices and the current one; `?rescan=1` re-scans `models/voices`.

- `GET /progress` → coarse progress of the current synthesis:

  `{"stage":1,"cur":0,"total":0}` where stage is `0` idle, `1` text frontend, `2` AR,

  `3` DiT/CFM, `4` vocoder, `5` done; `cur/total` counts AR tokens or DiT steps.

  The GAG GUI polls this for its progress bar.

- `GET /control` without `command` → `400 {"message":"command is required ..."}`. This is the

  api_v2-compatible liveness probe (the upstream GUI treats `400` as "API ready"); prefer

  `/health` for new clients.

- `GET /control?command=exit` → graceful shutdown (used by tests); `?command=restart` reloads

  the current voice.

- `GET /asr` → `501`, ASR is not part of this engine.

- `GET /docs`, `GET /openapi.json` → OpenAPI 3 document.

- `GET /tts_ws` → `501`: this build has no WebSocket support; use `POST /tts` with

  `stream: true` instead.

- `--parent-pid PID` (CLI) makes the server exit when that process disappears; the Windows

  one-click package uses it so closing the GUI frees the GPU.



## Examples



```bash

# one-shot

curl -s -X POST http://127.0.0.1:9880/tts -H 'Content-Type: application/json' \

  -d '{"text":"你好","text_lang":"zh","ref_audio_path":"/models/ref.wav",

       "prompt_text":"参考音频文本","sample_steps":4}' -o out.wav



# streaming to a player

curl -sN -X POST http://127.0.0.1:9880/tts -H 'Content-Type: application/json' \

  -d '{"text":"第一句。第二句。","ref_audio_path":"/models/ref.wav",

       "prompt_text":"参考音频文本","stream":true}' | ffplay -autoexit -



# default reference, then synthesize

curl -s "http://127.0.0.1:9880/change_refer?refer_wav_path=/models/ref.wav&prompt_text=%E5%8F%82%E8%80%83"

curl -s -X POST http://127.0.0.1:9880/tts -H 'Content-Type: application/json' -d '{"text":"你好"}'

```