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.

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:

{ "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

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.

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 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:

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.