API.md

# API reference

How this Space talks to VoxCPM2, and how you can do the same from your own code.

## This Space has no API of its own

`diatest/VoxCPM-Demo` is a **static** Space — one `index.html`, no server process,
nothing listening. There is no endpoint on `https://diatest-voxcpm-demo.static.hf.space`
to POST to.

| | |
|---|---|
| Repo page | https://huggingface.co/spaces/diatest/VoxCPM-Demo |
| Live app | https://diatest-voxcpm-demo.static.hf.space |
| SDK | `static`, public, no hardware |

What the page does is call the public Gradio API of the **official** Space from the
visitor's browser. Everything below is that API:

```
BASE = https://openbmb-voxcpm-demo.hf.space
```

Gradio's REST bridge is a two-step protocol: `POST /gradio_api/call/<endpoint>` returns
an `event_id`, then `GET /gradio_api/call/<endpoint>/<event_id>` streams the result as
Server-Sent Events. The payload you want arrives on `event: complete`; failures arrive
on `event: error`.

---

## 1. Upload a reference clip

Required before any call that takes audio. Returns a server-side path.

```bash
curl -X POST $BASE/gradio_api/upload -F "files=@reference.wav"
# ["/tmp/gradio/02a3dbd5.../reference.wav"]
```

Wherever an endpoint takes audio, pass that path wrapped as a Gradio `FileData`:

```json
{ "path": "/tmp/gradio/02a3dbd5.../reference.wav", "meta": { "_type": "gradio.FileData" } }
```

---

## 2. Generate speech — `/generate`

Arguments are **positional** in the `data` array. Order matters.

| # | Field | Type | Default | Notes |
|---|---|---|---|---|
| 0 | `text_input` | string | — | the text to speak |
| 1 | `control_instruction` | string | `""` | natural-language voice description |
| 2 | `reference_wav_path_input` | FileData \| null | `null` | clip to clone |
| 3 | `use_prompt_text` | bool | `false` | exact-clone mode |
| 4 | `prompt_text_input` | string | `""` | transcript of the reference clip |
| 5 | `cfg_value_input` | float | `2.0` | guidance scale |
| 6 | `do_normalize` | bool | `false` | normalize numbers/dates |
| 7 | `denoise` | bool | `false` | denoise the reference clip |

```bash
EID=$(curl -s -X POST $BASE/gradio_api/call/generate \
  -H "Content-Type: application/json" \
  -d '{"data":["Hello from VoxCPM.","",null,false,"",2.0,true,false]}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['event_id'])")

curl -N $BASE/gradio_api/call/generate/$EID
```

```
event: complete
data: [{"path":"/tmp/gradio/.../tmp4wz.mp3","url":"https://openbmb-voxcpm-demo.hf.space/gradio_api/file=/tmp/gradio/.../tmp4wz.mp3", ...}]
```

Fetch the `url` for the audio. It is an **MP3**, despite the raw-PCM naming elsewhere in
the VoxCPM ecosystem.

**Voice cloning:** upload the clip (step 1), then pass the `FileData` at index 2, `true`
at index 3, and the clip's transcript at index 4.

---

## 3. Transcribe a reference clip — `/_run_asr_if_needed`

SenseVoice ASR. The page uses it to auto-fill the transcript for exact-clone mode.

```bash
curl -X POST $BASE/gradio_api/call/_run_asr_if_needed \
  -H "Content-Type: application/json" \
  -d '{"data":[true,{"path":"/tmp/gradio/.../reference.wav","meta":{"_type":"gradio.FileData"}}]}'
```

Collect the event id as above. The response is a Gradio *update* object, so the text is
under `.value`, not the top level:

```
data: [{"placeholder":"…","value":"Just by listening a few minutes a day, …","__type__":"update"}]
```

---

## Behaviour worth knowing

- **No auth.** These endpoints answer anonymously — that is why a static page can drive
  them. No token, no key.
- **CORS reflects the calling origin**, so browser calls work from this Space and from
  `localhost` during development.
- **Latency** is roughly 3–7 s for a short sentence. Measured throughput saturates around
  2–4 concurrent requests; beyond that you are queueing, not parallelising.
- **`_`-prefixed endpoints are internal.** `_run_asr_if_needed` is a Gradio event handler,
  not a published API. It can be renamed or removed by any upstream redeploy.

---

## Do not put production traffic through this

The API above is **openbmb's infrastructure, not ours**. It is a free, shared Space
serving other people: no SLA, no capacity guarantee, and it can change shape or vanish
without notice. Sustained production load would also degrade it for everyone else using
the demo.

Fine for: demos, prototypes, experimentation, this Space.

Not fine for: an application backend.

### If you want a Space serving your own model

`gradio-app/` in this repo is a complete standalone Gradio app that loads VoxCPM locally
through the [`voxcpm`](https://pypi.org/project/voxcpm/) package — no upstream dependency.
It is written ZeroGPU-first and defaults to the smaller `openbmb/VoxCPM-0.5B` so it also
runs on CPU. Deploying it needs a PRO account, since Gradio Spaces are no longer on the
free tier:

```bash
hf repos create <ns>/VoxCPM-Self-Hosted --type space --space-sdk gradio \
    --flavor zero-a10g --public
hf upload <ns>/VoxCPM-Self-Hosted ./gradio-app . --repo-type space
```

See `gradio-app/README.md` for its environment variables.