Skip to content

API Reference

aivrar edited this page Nov 18, 2026 · 1 revision

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.

Typical flow

  1. Load the engine: POST /<engine>_load with {"device": "0"} ("cpu" works for Kokoro and Whisper)
  2. Generate: POST the inference endpoint with your payload
  3. Get the audio from the response:
    • no save_path → base64 audio in the JSON (audio_base64, or audios[] for music)
    • with save_path → saved under projects_output/<save_path>/, and the response says where (saved_to, saved_files)

Endpoints by engine

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

Status codes

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

End-to-end example (Python)

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.

Saving into a project instead

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

Full parameter lists

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.

Clone this wiki locally