3dtours/K.G.One

Files

T

Xiaohan-Tian 982ea97513 feat: allow user to customize services' ports; updated README.md

2026-04-17 22:40:16 -07:00

14 KiB

Raw Permalink Blame History

K.G.One API Reference

K.G.One exposes a REST API on port 8000. These endpoints are consumed by K.G.Studio's AI Musician Assistant and are also directly callable for programmatic or headless use.

Interactive docs (Swagger UI): http://localhost:8000/docs

System

Method	URL	Description
`GET`	`/health`	Server health check
`POST`	`/v1/models/load`	Load a model onto the GPU (unloads the active one first)
`GET`	`/v1/models/status`	Return the currently active model

`GET /health`

Response

{
  "status": "ok",
  "active_model": "clip"
}

active_model is null when no model is loaded.

`POST /v1/models/load`

Loads a model onto the GPU. If a different model is currently active, it is shut down first.

For "fullsong" and "clip" this call blocks until the sub-service reports healthy (model weights loaded). Expect 30–120 seconds on first run.

For "separator" it only terminates the currently running model to free VRAM — no persistent process is started. Returns immediately.

Request

Field	Type	Required	Values
`model`	string	yes	`"clip"`, `"fullsong"`, or `"separator"`

{ "model": "separator" }

Response

{
  "active_model": "separator",
  "status": "ready"
}

Error — unknown model (400)

{ "detail": "Unknown model 'foo'. Must be 'fullsong', 'clip', or 'separator'." }

`GET /v1/models/status`

Response

{
  "active_model": "fullsong"
}

Full-song generation (ACE-Step 1.5)

All /v1/fullsong/* endpoints return HTTP 503 if fullsong is not the active model.

Method	URL	Description
`POST`	`/v1/fullsong/generate`	Submit a full-song generation task
`GET`	`/v1/fullsong/result/{task_id}`	Poll task status and retrieve result
`GET`	`/v1/fullsong/audio/{task_id}`	Download a generated audio file

`POST /v1/fullsong/generate`

Proxied to ACE-Step's /release_task. All listed fields are forwarded as-is; any additional ACE-Step fields are also accepted and passed through.

See ACE-Step API docs for the complete parameter spec.

Request

Field	Type	Default	Description
`caption`	string	required	Musical style/description
`lyrics`	string	`null`	Song lyrics (`[verse]`, `[chorus]` tags supported)
`instrumental`	boolean	`null`	Generate without vocals
`inference_steps`	integer	`null`	Diffusion steps (8 = turbo, 50 = full quality)
`guidance_scale`	number	`null`	Classifier-free guidance scale
`use_random_seed`	boolean	`null`	Use a random seed
`seed`	integer	`null`	Fixed seed value (used when `use_random_seed` is false)
`thinking`	boolean	`null`	Enable ACE-Step thinking mode
`batch_size`	integer	`null`	Number of outputs to generate
`audio_format`	string	`null`	`"mp3"`, `"wav"`, `"flac"`, `"opus"`

Example request

curl -X POST 'http://127.0.0.1:8000/v1/fullsong/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "Genre: Eurodance, 90s dance-pop, upbeat electronic. Catchy, energetic, nostalgic 90s Eurodance with a strong four-on-the-floor beat. Bright synth leads, punchy bassline. Tempo: ~130 BPM.",
    "lyrics": "[verse]\nStep in the scene, yeah the bassline drops\n[chorus]\nWe are dancing in the neon in the night",
    "instrumental": false,
    "inference_steps": 8,
    "guidance_scale": 7.0,
    "use_random_seed": true,
    "thinking": true,
    "batch_size": 1,
    "audio_format": "mp3"
  }'

Response

{
  "data": {
    "task_id": "58e15e57-3022-4f43-8ada-64ea52a9064a",
    "status": "queued",
    "queue_position": 1
  },
  "code": 200,
  "error": null,
  "timestamp": 1776227065582,
  "extra": null
}

`GET /v1/fullsong/result/{task_id}`

Poll until status is 1 (succeeded). Recommended interval: 2–5 seconds.

Response — pending / running

{
  "data": [
    {
      "task_id": "58e15e57-3022-4f43-8ada-64ea52a9064a",
      "status": 0,
      "progress": 0.1,
      "stage": "Phase 1: Generating CoT metadata..."
    }
  ],
  "code": 200
}

Response — succeeded

{
  "data": [
    {
      "task_id": "58e15e57-3022-4f43-8ada-64ea52a9064a",
      "status": 1,
      "progress": 1.0,
      "stage": "succeeded"
    }
  ],
  "code": 200
}

Once status is 1, download the audio with GET /v1/fullsong/audio/{task_id}.

`GET /v1/fullsong/audio/{task_id}`

Download the generated audio file. Only works once the task has succeeded (status == 1).

Query parameter: index (optional, default 0) — selects a specific file when batch_size > 1.

Example

curl -X GET \
  'http://127.0.0.1:8000/v1/fullsong/audio/58e15e57-3022-4f43-8ada-64ea52a9064a?index=0' \
  --output song.mp3

Response headers

content-disposition: attachment; filename="58e15e57-3022-4f43-8ada-64ea52a9064a.mp3"
content-type: audio/mpeg

Clip generation (Foundation-1)

All /v1/clip/* endpoints return HTTP 503 if clip is not the active model.

Foundation-1 generates short instrument clips (4 or 8 bars) from a structured text prompt, producing both a WAV audio file and a MIDI transcription simultaneously.

Method	URL	Description
`POST`	`/v1/clip/generate`	Submit a clip generation task
`GET`	`/v1/clip/result/{task_id}`	Poll task status
`GET`	`/v1/clip/audio/{task_id}`	Download the generated WAV file
`GET`	`/v1/clip/midi/{task_id}`	Download the generated MIDI file

`POST /v1/clip/generate`

Request

Field	Type	Default	Description
`prompt`	string	required	Comma-separated descriptor tags (see prompt guide below)
`negative_prompt`	string	`""`	Tags to avoid
`bars`	integer	`4`	Clip length: `4` or `8`
`bpm`	integer	`140`	Tempo in BPM (e.g. 100, 110, 120, 128, 130, 140, 150)
`note`	string	`"C"`	Root note: `A` through `G#`
`scale`	string	`"minor"`	`"major"` or `"minor"`
`steps`	integer	`75`	Diffusion steps (1–500; 75 is a good balance)
`cfg_scale`	number	`7.0`	Classifier-free guidance (0–25)
`seed`	integer	`-1`	`-1` for random
`sampler_type`	string	`"dpmpp-2m-sde"`	Sampler algorithm
`sigma_min`	number	`0.03`	Minimum noise sigma
`sigma_max`	number	`500.0`	Maximum noise sigma
`cfg_rescale`	number	`0.0`	CFG rescale factor (0–1)

Prompt format

Foundation-1 prompts are structured tag lists:

[Instrument family], [Sub-type], [Timbre descriptors], [FX], [Bars], [BPM], [Key]

Examples:

"Piano, Rhodes Piano, Warm, Bright, Lush, 8 Bars, 120 BPM, C major"
"Bass, FM Bass, Acid, Gritty, Thick, 8 Bars, 140 BPM, E minor"
"Synth, Wavetable Synth, Pad, Wide, Silky, 4 Bars, 128 BPM, A minor"

Example request

curl -X POST 'http://127.0.0.1:8000/v1/clip/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Gritty, Acid, Bassline, 303, Synth Lead, FM, Sub, Upper Mids, High Phaser, High Reverb, Pitch Bend, 8 Bars, 140 BPM, E minor",
    "bars": 8,
    "bpm": 140,
    "note": "E",
    "scale": "minor",
    "steps": 75,
    "cfg_scale": 7,
    "seed": -1,
    "sampler_type": "dpmpp-2m-sde",
    "sigma_min": 0.03,
    "sigma_max": 500,
    "cfg_rescale": 0
  }'

Response

{
  "task_id": "7ab55a6a-c478-45a0-bab7-1fd9cbd8597d"
}

`GET /v1/clip/result/{task_id}`

Poll until status is "complete". Recommended interval: 2–5 seconds.

Response — pending / running

{
  "task_id": "7ab55a6a-c478-45a0-bab7-1fd9cbd8597d",
  "status": "running",
  "error": null
}

Response — complete

{
  "task_id": "7ab55a6a-c478-45a0-bab7-1fd9cbd8597d",
  "status": "complete"
}

Once complete, download the files using the same task_id:

GET /v1/clip/audio/{task_id} → WAV
GET /v1/clip/midi/{task_id} → MIDI

Response — error

{
  "task_id": "7ab55a6a-c478-45a0-bab7-1fd9cbd8597d",
  "status": "error",
  "error": "Generation failed — check server logs."
}

`GET /v1/clip/audio/{task_id}`

Download the generated WAV file (32 kHz stereo).

curl -X GET \
  'http://127.0.0.1:8000/v1/clip/audio/7ab55a6a-c478-45a0-bab7-1fd9cbd8597d' \
  --output clip.wav

Response headers

content-type: audio/wav
content-length: 2419244

`GET /v1/clip/midi/{task_id}`

Download the MIDI transcription (via basic-pitch).

curl -X GET \
  'http://127.0.0.1:8000/v1/clip/midi/7ab55a6a-c478-45a0-bab7-1fd9cbd8597d' \
  --output clip.mid

Response headers

content-type: audio/midi
content-length: 1458

Stem separation (python-audio-separator)

All /v1/separator/* endpoints return HTTP 503 if separator is not the active model.

Separates an uploaded audio file into individual stems using UVR models. Outputs are always MP3.

Method	URL	Description
`POST`	`/v1/separator/separate`	Upload audio + select model → task ID
`GET`	`/v1/separator/result/{task_id}`	Poll task status and retrieve output filenames
`GET`	`/v1/separator/download/{filename}`	Download a separated stem file

`POST /v1/separator/separate`

Accepts multipart/form-data.

Form fields

Field	Type	Required	Description
`file`	file	yes	Audio file to separate (MP3, WAV, FLAC, …)
`model_filename`	string	yes	One of the supported models below

Supported models

`model_filename`	Stems produced
`UVR-MDX-NET-Inst_HQ_3.onnx`	2 — Vocals, Instrumental
`MDX23C-8KFFT-InstVoc_HQ.ckpt`	2 — Vocals, Instrumental
`htdemucs_6s.yaml`	6 — bass, drums, guitar, other, piano, vocals

Models are downloaded automatically by audio-separator on first use.

Example request

curl -X POST 'http://127.0.0.1:8000/v1/separator/separate' \
  -H 'accept: application/json' \
  -F 'file=@song.mp3;type=audio/mpeg' \
  -F 'model_filename=MDX23C-8KFFT-InstVoc_HQ.ckpt'

Response

{ "task_id": "0b93cb76-616d-45f0-9580-61d615cd6a76" }

`GET /v1/separator/result/{task_id}`

Poll until status is "complete". Separation typically takes 10–60 seconds.

Response — running

{
  "task_id": "0b93cb76-616d-45f0-9580-61d615cd6a76",
  "status": "running"
}

Response — complete

{
  "task_id": "0b93cb76-616d-45f0-9580-61d615cd6a76",
  "status": "complete",
  "files": [
    "0b93cb76-616d-45f0-9580-61d615cd6a76_(Instrumental)_MDX23C-8KFFT-InstVoc_HQ.mp3",
    "0b93cb76-616d-45f0-9580-61d615cd6a76_(Vocals)_MDX23C-8KFFT-InstVoc_HQ.mp3"
  ]
}

Response — error

{
  "task_id": "0b93cb76-616d-45f0-9580-61d615cd6a76",
  "status": "error",
  "error": "Separation failed — check server logs."
}

`GET /v1/separator/download/{filename}`

Download a stem MP3 file. filename is one of the entries from the files list above.

curl -X GET \
  'http://127.0.0.1:8000/v1/separator/download/0b93cb76-616d-45f0-9580-61d615cd6a76_%28Vocals%29_MDX23C-8KFFT-InstVoc_HQ.mp3' \
  --output vocals.mp3

Response headers

content-disposition: attachment; filename="0b93cb76-...(Vocals)_MDX23C-8KFFT-InstVoc_HQ.mp3"
content-type: audio/mpeg

Typical Workflows

Generate a full song

# 1. Load ACE-Step
curl -X POST http://localhost:8000/v1/models/load \
  -H "Content-Type: application/json" \
  -d '{"model": "fullsong"}'

# 2. Submit generation
TASK=$(curl -s -X POST http://localhost:8000/v1/fullsong/generate \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "lo-fi hip hop, mellow piano, soft drums, vinyl crackle",
    "instrumental": true,
    "inference_steps": 8,
    "use_random_seed": true,
    "audio_format": "mp3"
  }' | python -c "import sys,json; print(json.load(sys.stdin)['data']['task_id'])")

# 3. Poll until status == 1
curl http://localhost:8000/v1/fullsong/result/$TASK

# 4. Download
curl "http://localhost:8000/v1/fullsong/audio/$TASK" --output song.mp3

Generate a MIDI + WAV clip

# 1. Load Foundation-1
curl -X POST http://localhost:8000/v1/models/load \
  -H "Content-Type: application/json" \
  -d '{"model": "clip"}'

# 2. Submit generation
TASK=$(curl -s -X POST http://localhost:8000/v1/clip/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Keys, Rhodes Piano, Warm, Lush, 8 Bars, 90 BPM, D major",
    "bars": 8, "bpm": 90, "note": "D", "scale": "major", "steps": 75
  }' | python -c "import sys,json; print(json.load(sys.stdin)['task_id'])")

# 3. Poll until status == "complete"
curl http://localhost:8000/v1/clip/result/$TASK

# 4. Download both files
curl "http://localhost:8000/v1/clip/audio/$TASK" --output clip.wav
curl "http://localhost:8000/v1/clip/midi/$TASK"  --output clip.mid

Separate stems from an audio file

# 1. Load separator (frees VRAM from any active model)
curl -X POST http://localhost:8000/v1/models/load \
  -H "Content-Type: application/json" \
  -d '{"model": "separator"}'

# 2. Submit separation
TASK=$(curl -s -X POST http://localhost:8000/v1/separator/separate \
  -F "file=@song.mp3" \
  -F "model_filename=UVR-MDX-NET-Inst_HQ_3.onnx" | python -c "import sys,json; print(json.load(sys.stdin)['task_id'])")

# 3. Poll until complete
curl http://localhost:8000/v1/separator/result/$TASK

# 4. Download stems (use filenames from the result response)
curl "http://localhost:8000/v1/separator/download/...(Vocals)....mp3" --output vocals.mp3
curl "http://localhost:8000/v1/separator/download/...(Instrumental)....mp3" --output instrumental.mp3

Error Reference

HTTP Status	Meaning
`400`	Bad request (e.g. unknown model name)
`404`	Task ID or file not found
`503`	Requested model is not currently loaded, or sub-service is unreachable

503 body when wrong model is active:

{
  "detail": {
    "error": "Model 'clip' is not loaded. POST /v1/models/load first.",
    "active_model": "fullsong"
  }
}

14 KiB Raw Permalink Blame History Unescape Escape

K.G.One API Reference

System

GET /health

POST /v1/models/load

GET /v1/models/status

Full-song generation (ACE-Step 1.5)

POST /v1/fullsong/generate

GET /v1/fullsong/result/{task_id}

GET /v1/fullsong/audio/{task_id}

Clip generation (Foundation-1)

POST /v1/clip/generate

GET /v1/clip/result/{task_id}

GET /v1/clip/audio/{task_id}

GET /v1/clip/midi/{task_id}

Stem separation (python-audio-separator)

POST /v1/separator/separate

GET /v1/separator/result/{task_id}

GET /v1/separator/download/{filename}

Typical Workflows

Generate a full song

Generate a MIDI + WAV clip

Separate stems from an audio file

Error Reference

14 KiB

Raw Permalink Blame History

`GET /health`

`POST /v1/models/load`

`GET /v1/models/status`

`POST /v1/fullsong/generate`

`GET /v1/fullsong/result/{task_id}`

`GET /v1/fullsong/audio/{task_id}`

`POST /v1/clip/generate`

`GET /v1/clip/result/{task_id}`

`GET /v1/clip/audio/{task_id}`

`GET /v1/clip/midi/{task_id}`

`POST /v1/separator/separate`

`GET /v1/separator/result/{task_id}`

`GET /v1/separator/download/{filename}`