Repository navigation
API Reference
Everything in the web UI is a plain JSON REST call, so you can drive LocalSoundsAPI from Python, Node, curl, n8n, a game engine, or another machine on your network.
Base URL: http://127.0.0.1:5006 (or the port you started the instance on)
💡 The quickest way to build a request: set it up in the UI, then click the panel's API Payload button. It shows the exact JSON that panel sends.
-
Load the engine:
POST /<engine>_loadwith{"device": "0"}("cpu"works for Kokoro and Whisper) -
Generate:
POSTthe inference endpoint with your payload -
Get the audio from the response:
- no
save_path→ base64 audio in the JSON (audio_base64, oraudios[]for music) - with
save_path→ saved underprojects_output/<save_path>/, and the response says where (saved_to,saved_files)
- no
| Engine | Load / Unload / Status | Generate | Stop |
|---|---|---|---|
| XTTS |
/load · /unload · /status
|
POST /infer |
/xtts_cancel |
| Fish Speech |
/fish_load · /fish_unload · /fish_status
|
POST /fish_infer |
/fish_cancel |
| Kokoro |
/kokoro_load · /kokoro_unload · /kokoro_status
|
POST /kokoro_infer |
/kokoro_stop |
| Stable Audio |
/stable_load · /stable_unload · /stable_status
|
POST /stable_infer |
/stable_cancel |
| ACE-Step |
/ace_load · /ace_unload · /ace_status
|
POST /ace_infer |
n/a |
| Whisper |
/whisper_load · /whisper_unload · /whisper_status
|
POST /voice_transcribe |
/voice_transcribe_cancel |
Voices & lists: GET /voices (cloning clips) · GET /speakers (XTTS built-in) · GET /kokoro_voices · POST /upload (multipart file)
Jobs: GET /job_status (see Concurrency & Progress)
Video: POST /transcribe · POST /make_video · GET /list_audio · GET /list_images
Chatbot: /chatbot/*, /lmstudio/*, /openrouter/*
Admin: POST /shutdown
| Code | Meaning |
|---|---|
200 |
Done. For speech jobs that couldn't finish every chunk, the body has "status": "incomplete" and a recover_command (##recover## + save path) to resume |
400 |
Bad request (missing text, unknown voice, …) |
409 |
Another engine's running job is using that save_path
|
499 |
Cancelled with Stop |
503 |
Engine busy (generating, loading or unloading). Retry after the Retry-After seconds |
500 |
Unexpected server error |
import base64, time, requests
API = "http://127.0.0.1:5006"
def post(path, payload=None):
"""POST, waiting politely while the engine is busy (503)."""
while True:
r = requests.post(API + path, json=payload or {}, timeout=3600)
if r.status_code != 503:
r.raise_for_status()
return r.json()
time.sleep(int(r.headers.get("Retry-After", 5)))
# 1. Narration with Kokoro (CPU is fine)
post("/kokoro_load", {"device": "cpu"})
speech = post("/kokoro_infer", {
"text": "Welcome back to the channel. Today we're exploring lighthouses.",
"voice": "am_michael",
"kokoroDeviceSelect": "cpu",
"output_format": "wav",
})
open("narration.wav", "wb").write(base64.b64decode(speech["audio_base64"]))
# 2. A sound effect with Stable Audio (GPU 0), two variants ranked by CLAP
post("/stable_load", {"device": "0"})
sfx = post("/stable_infer", {
"prompt": "ocean waves crashing on rocks, seagulls, wind",
"steps": 100, "length": 10, "num_waveforms_per_prompt": 2,
})
best = next(a for a in sfx["audios"] if a["is_best"])
open("waves.wav", "wb").write(base64.b64decode(best["audio_base64"]))Both engines can run at the same time from two threads or processes. Same-engine requests wait their turn via the 503 / Retry-After loop.
{"text": "Chapter one...", "voice": "af_heart", "save_path": "MyAudiobook"}The audio is written to projects_output/MyAudiobook/ along with job.json, so the job can be resumed with "text": "##recover##" if it stops part-way.
Every field for every endpoint is documented in chapter 14 of the manual, and [stand-alone-app]-API_client.py in the repo is a complete working client.
LocalSoundsAPI · Latest release · PDF manual · Issues · MIT licensed
Get started
Speech
Music & sound
Production
Developers
Help