3dtours/K.G.One
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: allow user to customize services' ports; updated README.md

Browse Source
This commit is contained in:
Xiaohan-Tian
2026-04-17 22:40:16 -07:00
parent 20b77d70ec
commit 982ea97513
4 changed files with 706 additions and 562 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+550
View File
@@ -0,0 +1,550 @@
# 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**
```json
{
"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"` |
```json
{ "model": "separator" }
```
**Response**
```json
{
"active_model": "separator",
"status": "ready"
}
```
**Error — unknown model (400)**
```json
{ "detail": "Unknown model 'foo'. Must be 'fullsong', 'clip', or 'separator'." }
```
---
### `GET /v1/models/status`
**Response**
```json
{
"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](https://github.com/ace-step/ACE-Step-1.5/blob/main/docs/en/API.md) 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**
```bash
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**
```json
{
"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**
```json
{
"data": [
{
"task_id": "58e15e57-3022-4f43-8ada-64ea52a9064a",
"status": 0,
"progress": 0.1,
"stage": "Phase 1: Generating CoT metadata..."
}
],
"code": 200
}
```
**Response — succeeded**
```json
{
"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**
```bash
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**
```bash
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**
```json
{
"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**
```json
{
"task_id": "7ab55a6a-c478-45a0-bab7-1fd9cbd8597d",
"status": "running",
"error": null
}
```
**Response — complete**
```json
{
"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**
```json
{
"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).
```bash
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](https://github.com/spotify/basic-pitch)).
```bash
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**
```bash
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**
```json
{ "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**
```json
{
"task_id": "0b93cb76-616d-45f0-9580-61d615cd6a76",
"status": "running"
}
```
**Response — complete**
```json
{
"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**
```json
{
"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.
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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:**
```json
{
"detail": {
"error": "Model 'clip' is not loaded. POST /v1/models/load first.",
"active_model": "fullsong"
}
}
```