{ "openapi": "3.1.0", "info": { "title": "Song Creator Pro Desktop API", "description": "HTTP API for AI music generation, stem separation, and the Song Creator Pro library.\n\n## Base URL\n\nThe API runs on your computer at `http://127.0.0.1:8200`. Turn it on under\nSettings → HTTP API and restart the app. Change the port there or start the\napp with `--api-port`. Start with `--headless` to serve the API with no window.\nEvery route starts with `/api/v1/`.\n\nWhile the API is running, the app also serves this reference: the OpenAPI spec\nat `/openapi.json`, Swagger UI at `/docs` and ReDoc at `/redoc`. Once a key is\nset these need it too; open `/docs?api_key=...` and the page passes it on.\n\n## Quick start\n\n1. `GET /api/v1/health` — check the server is up\n2. `POST /api/v1/model/initialize` — load the model (required before generating)\n3. `GET /api/v1/model/status` — poll until `status: \"ready\"`\n4. `POST /api/v1/generation/start` — start a generation\n5. `GET /api/v1/generation/progress` — poll until `status: \"complete\"`\n6. `GET /api/v1/generation/result` — collect the result\n7. `GET /api/v1/audio/download?path=...` — download the audio\n\n## Generation is asynchronous\n\nGeneration runs for minutes, so there is no synchronous mode. Start, poll,\nthen collect. Only one generation runs at a time; starting a second returns 409.\n\n## Authentication\n\nNo key is needed unless you set one under Settings → HTTP API, start the app\nwith `--api-key`, or set `SCP_API_KEY`. Once set, send it as `X-API-Key`,\n`Authorization: Bearer`, or `?api_key=`. Only `/api/v1/health` and\n`/api/v1/system/version` are exempt. Binding to anything other than localhost\nwith `--host` requires a key.", "version": "1.0.0" }, "paths": { "/api/v1/health": { "get": { "tags": [ "Health" ], "summary": "Check the server is up", "description": "Cheapest way to confirm the API is reachable. Never requires an API key, so a client can probe a server before it knows the credentials.", "operationId": "health_api_v1_health_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok" } } } } }, "security": [] } }, "/api/v1/system/version": { "get": { "tags": [ "Health" ], "summary": "Get the app version", "description": "Version string from the bundled version.txt, or `dev` when running from a source checkout. Exempt from authentication so a client can identify a server before authenticating.", "operationId": "version_api_v1_system_version_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "example": { "version": "1.4.4.0" } } } } }, "security": [] } }, "/api/v1/system/gpu": { "get": { "tags": [ "System" ], "summary": "Get GPU capabilities", "description": "Detected hardware and the limits it implies: capability tier, VRAM, the longest track and largest batch this machine can generate, and the devices that can be selected. Read this before choosing generation parameters. An ACE-Step text-to-music run that uses the language model stops at `max_duration` and says so in the result's `warnings`; other runs are not capped and can run out of GPU memory.", "operationId": "gpu_config_api_v1_system_gpu_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpuConfigResponse" }, "example": { "tier": "high", "gpu_name": "NVIDIA GeForce RTX 4090", "gpu_memory_gb": 24.0, "max_duration": 240.0, "max_batch": 4, "available_devices": [ "auto", "cuda", "cpu" ] } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/system/backend": { "get": { "tags": [ "System" ], "summary": "Get the active PyTorch backend", "description": "Which acceleration backend setup installed. Returns `unknown` before first-run setup has completed.", "operationId": "current_backend_api_v1_system_backend_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendResponse" }, "example": { "backend": "cuda" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/setup/status": { "get": { "tags": [ "Setup" ], "summary": "Check whether first-run setup is needed", "description": "True when the backend packages (PyTorch and friends) are not yet installed. Generation cannot start until setup completes.", "operationId": "status_api_v1_setup_status_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStatusResponse" }, "example": { "required": false } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/setup/options": { "get": { "tags": [ "Setup" ], "summary": "List installable backends", "description": "Acceleration backends available for this machine, with the recommended one marked. Entries with `available: false` were detected but cannot run on this GPU. Feed an entry's id to `POST /api/v1/setup/start`.", "operationId": "options_api_v1_setup_options_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SetupOption" }, "type": "array", "title": "Response 200 Options Api V1 Setup Options Get" }, "example": [ { "id": "cuda", "name": "NVIDIA CUDA 12.8", "gpu_name": "NVIDIA GeForce RTX 4090", "recommended": true, "download_size": "3.8 GB", "description": "GPU acceleration for NVIDIA GPUs" }, { "id": "cpu", "name": "CPU Only", "recommended": false, "download_size": "620 MB", "description": "No GPU acceleration (slower)" } ] } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/setup/start": { "post": { "tags": [ "Setup" ], "summary": "Start installing a backend", "description": "Begins a multi-gigabyte download and install in the background and returns immediately. Poll `GET /api/v1/setup/progress` until status is `complete`. The app must be restarted afterwards. Returns `started: false` with a `reason` when an install is already running.", "operationId": "start_api_v1_setup_start_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartedResponse" }, "example": { "started": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/setup/progress": { "get": { "tags": [ "Setup" ], "summary": "Poll setup progress", "description": "Current state of a running install. Status moves `idle` → `downloading` → `complete`, or `error` with the reason in `message`.", "operationId": "progress_api_v1_setup_progress_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupProgressResponse" }, "example": { "status": "downloading", "message": "Installing torch...", "percent": 40 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/setup/reset": { "post": { "tags": [ "Setup" ], "summary": "Queue a backend reinstall", "description": "Marks the installed packages for deletion on next launch — they cannot be removed while their DLLs are loaded. Optionally names the backend to install afterwards. Requires a restart to take effect.\n\nThis endpoint reports failure in the body rather than the status code: a 200 with `success: false` and an `error` string. Check `success`, not the status.", "operationId": "reset_api_v1_setup_reset_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupResetRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResult" }, "example": { "success": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/settings": { "get": { "tags": [ "Settings" ], "summary": "Get all settings", "description": "Current generation settings: selected models per mode, device, quantization, CPU offload, and language-model options. Empty model choices are resolved to the defaults actually in use, so what you read is what generation will use.", "operationId": "get_settings_api_v1_settings_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" }, "example": { "device": "auto", "config_path": "acestep-v15-turbo", "config_path_custom": "acestep-v15-sft", "config_path_cover": "acestep-v15-turbo", "config_path_base": "acestep-v15-base", "lm_model_path": "acestep-5Hz-lm-1.7B", "init_llm": true, "backend": "pt", "quantization": false, "offload_to_cpu": false, "offload_dit_to_cpu": false, "compile_model": false, "use_flash_attention": true, "gpu_tier": "high", "yue2_quantization": "none" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } }, "put": { "tags": [ "Settings" ], "summary": "Update settings", "description": "Applies each supplied key and returns the full settings afterwards. Keys are applied individually and independently: an unknown or rejected key does not stop the others, and the response is still 200. Compare the returned values against what you sent to confirm each one landed.\n\nModel-selection changes take effect on the next generation; some others need a model reload.", "operationId": "update_settings_api_v1_settings_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" }, "example": { "device": "auto", "config_path": "acestep-v15-turbo", "config_path_custom": "acestep-v15-sft", "config_path_cover": "acestep-v15-turbo", "config_path_base": "acestep-v15-base", "lm_model_path": "acestep-5Hz-lm-1.7B", "init_llm": true, "backend": "pt", "quantization": false, "offload_to_cpu": false, "offload_dit_to_cpu": false, "compile_model": false, "use_flash_attention": true, "gpu_tier": "high", "yue2_quantization": "none" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/settings/preferences/{key}": { "get": { "tags": [ "Settings" ], "summary": "Read a UI preference", "description": "Preferences are free-form UI state — panel widths, theme, volume. Returns null for a key that was never set.", "operationId": "get_preference_api_v1_settings_preferences__key__get", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "description": "Preference name. Free-form; the desktop UI uses keys such as `theme`, `player_volume` and `panel_left_width`. Separate from `/api/v1/settings`.", "title": "Key" }, "description": "Preference name. Free-form; the desktop UI uses keys such as `theme`, `player_volume` and `panel_left_width`. Separate from `/api/v1/settings`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceResponse" }, "example": { "key": "theme", "value": "dark" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Settings" ], "summary": "Write a UI preference", "description": "Stores any JSON-serialisable value under the key. Used by the desktop UI to persist layout and playback state.", "operationId": "set_preference_api_v1_settings_preferences__key__put", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "description": "Preference name. Free-form; the desktop UI uses keys such as `theme`, `player_volume` and `panel_left_width`. Separate from `/api/v1/settings`.", "title": "Key" }, "description": "Preference name. Free-form; the desktop UI uses keys such as `theme`, `player_volume` and `panel_left_width`. Separate from `/api/v1/settings`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResult" }, "example": { "success": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "summary": "List locally available models", "description": "What is already on disk and usable without a download: generation checkpoints, language models, and LoRA adapters.", "operationId": "available_models_api_v1_models_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableModelsResponse" }, "example": { "checkpoints": [ "acestep-v15-turbo" ], "lm_models": [], "lora_models": [ "mylora.safetensors" ] } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/models/catalog": { "get": { "tags": [ "Models" ], "summary": "List all known models with download state", "description": "Every model the app knows about, each flagged with whether it is downloaded. XL variants are listed on CUDA/ROCm GPUs with 12 GB or more of VRAM; below 16 GB they always load with INT8 quantization and CPU offload.", "operationId": "catalog_api_v1_models_catalog_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalogResponse" }, "example": { "dit_models": [ { "id": "acestep-v15-turbo", "downloaded": true }, { "id": "acestep-v15-sft", "downloaded": false } ], "lm_models": [ { "id": "acestep-5Hz-lm-1.7B", "downloaded": false } ], "yue2_models": [ { "id": "YuE2-3B", "downloaded": true }, { "id": "YuE2-Vae", "downloaded": true } ] } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/models/download": { "post": { "tags": [ "Models" ], "summary": "Start downloading a model", "description": "Begins a background download of several gigabytes and returns immediately. Poll `GET /api/v1/models/download/status`. Downloading is rarely necessary: generation fetches a missing model automatically.\n\nTo repair a damaged model, send `fresh: true`: the model's folder is deleted and downloaded again from scratch. `GET /api/v1/model/status` names the model to repair in `error.model`.\n\nA refused download is a 200 with `started: false` and the `reason`, such as another download already running.", "operationId": "start_download_api_v1_models_download_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDownloadRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartedResponse" }, "example": { "started": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/models/download/status": { "get": { "tags": [ "Models" ], "summary": "Poll download progress", "description": "State of the current or most recent model download.", "operationId": "download_status_api_v1_models_download_status_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadStatusResponse" }, "example": { "status": "downloading", "model": "acestep-v15-sft", "percent": 12 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/models/download/cancel": { "post": { "tags": [ "Models" ], "summary": "Cancel the running download", "description": "Signals the download to stop. Returns `cancelled: false` when nothing was running. Partial files are kept so a later download resumes from them.", "operationId": "cancel_download_api_v1_models_download_cancel_post", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" }, "example": { "cancelled": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/engines": { "get": { "tags": [ "Engines" ], "summary": "List generation engines", "description": "ACE-Step and YuE2 with availability for this hardware, download state and FP8 support.", "operationId": "engine_catalog_api_v1_engines_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineCatalogResponse" }, "example": { "engines": [ { "id": "acestep", "display_name": "ACE-Step 1.5", "available": true, "downloaded": true, "fp8_supported": false, "cover_tools_downloaded": false, "cover_tools_download_size_gb": 0.0, "lyrics_transcriber_downloaded": false, "lyrics_transcriber_download_size_gb": 4.7 } ], "active_engine": "acestep" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/engines/validate-abc": { "post": { "tags": [ "Engines" ], "summary": "Validate an ABC score", "description": "Parse a YuE2 score and return a summary or the first error. Used by the score editor.", "operationId": "validate_abc_api_v1_engines_validate_abc_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateAbcRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateAbcResponse" }, "example": { "ok": true, "summary": "48 bars, meter 4/4, tempo 83" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/engines/move-note": { "post": { "tags": [ "Engines" ], "summary": "Move a note in an ABC score", "description": "Moves the note between the given character offsets up or down by staff steps (negative is up). Every other note keeps its pitch: accidentals the move would disturb are written out explicitly. Tied notes cannot be moved. Offsets refer to the score with line endings normalised to LF, and the returned score uses LF.", "operationId": "move_note_api_v1_engines_move_note_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveNoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveNoteResponse" }, "example": { "ok": true, "text": "X:1 ... (the full edited score)", "pitch": 74 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/engines/score-map": { "post": { "tags": [ "Engines" ], "summary": "Read a score as a song map", "description": "Splits a YuE2 score into its sections with bar ranges, timing and per-bar chords, pairs each section with a tagged lyric block by label and order, and lists the keys the song can move to. Returns `ok: false` with the validator's message for a score that does not parse.", "operationId": "score_map_api_v1_engines_score_map_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreMapRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreMapResponse" }, "example": { "ok": true, "key": "C", "tempo": 120, "meter": "4/4", "seconds": 16.0, "bars": 8, "has_chords": true, "sections": [ { "label": "verse", "first_bar": 1, "bar_count": 4, "start": 0.0, "seconds": 8.0, "instrumental": false, "lyric": { "index": 0, "label": "Verse", "first_line": "Neon fades along the lane" }, "bars": [ { "number": 1, "start": 0.0, "rest": false, "chords": [ { "symbol": "C", "offset": 0.0 } ] } ] } ], "unused_lyrics": [], "transpose_options": [ { "semitones": 2, "key": "D" } ], "key_chords": [ "C", "Dm", "Em", "F", "G", "Am", "Bdim" ], "chord_roots": [ "C", "C#", "Db" ], "chord_qualities": [ "", "m", "7" ], "tempo_range": [ 40, 240 ] } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/engines/edit-score": { "post": { "tags": [ "Engines" ], "summary": "Apply a song map edit", "description": "Applies one change to a score and its lyrics. The `edit` object takes one of these shapes: `{\"op\": \"duplicate\"|\"delete\", \"section\": i}` (sections count from 0; the paired lyric block is copied or removed with it), `{\"op\": \"move\", \"section\": i, \"to\": j}` (the paired lyric block moves with it), `{\"op\": \"set_chord\", \"bar\": b, \"index\": k, \"chord\": \"Dm7\"}` (bars count from 1; `index` picks the chord within the bar, and 0 adds one to a bar without), `{\"op\": \"transpose\", \"semitones\": n}` (-6 to 6, not 0) or `{\"op\": \"set_tempo\", \"bpm\": q}` (a whole number from 40 to 240). For structure and chord edits every other note keeps its pitch. A change that would leave an invalid score is refused with a reason and nothing changes.", "operationId": "edit_score_api_v1_engines_edit_score_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditScoreResponse" }, "example": { "ok": true, "text": "X:1 ... (the full edited score)", "lyrics": "[Chorus]\n..." } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/model/initialize": { "post": { "tags": [ "Model" ], "summary": "Load the generation model", "description": "**Required before any generation.** Loads the model in the background and returns immediately; poll `GET /api/v1/model/status` until status is `ready`. Missing model files are downloaded first, so a cold start can take a long time. Optionally accepts settings to apply before loading.", "operationId": "initialize_api_v1_model_initialize_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitializeRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitializeResponse" }, "example": { "success": true, "message": "Initialization started" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "409": { "description": "Setup has not completed, so there is nothing to load. Run the setup endpoints first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/model/reinitialize": { "post": { "tags": [ "Model" ], "summary": "Reload the model with new settings", "description": "Applies the supplied settings, drops the language model so it is recreated, and reloads. Use after changing quantization, device, or CPU offload, which cannot be applied to an already-loaded model.", "operationId": "reinitialize_api_v1_model_reinitialize_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitializeRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitializeResponse" }, "example": { "success": true, "message": "Initialization started" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "409": { "description": "Setup has not completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/model/status": { "get": { "tags": [ "Model" ], "summary": "Poll model load progress", "description": "Status moves `idle` → `loading` → `ready`, or `error` with the reason in `message` and a full traceback in `detail`. Generation is refused until this reads `ready`.\n\nOn `error`, `error` names the cause and the steps that fix it. When `error.cause` is `checkpoint` and `error.model` is set, repair it with `POST /api/v1/models/download` and `fresh: true`, then `POST /api/v1/model/initialize`.", "operationId": "status_api_v1_model_status_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitStatusResponse" }, "example": { "status": "ready", "message": "Ready", "percent": 100 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/model/llm/unload": { "post": { "tags": [ "Model" ], "summary": "Unload the language model", "description": "Frees the VRAM held by the lyric and caption assistant while leaving the generation model loaded. Generation then runs without it until `init_llm` is set back to true; lyric generation, caption enhancement and source analysis still load it on demand.", "operationId": "unload_llm_api_v1_model_llm_unload_post", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResult" }, "example": { "success": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/start": { "post": { "tags": [ "Generation" ], "summary": "Start a generation", "description": "Starts generation in the background and returns immediately. Poll `GET /api/v1/generation/progress` until status is `complete`, then collect `GET /api/v1/generation/result`.\n\n`task_type` selects the mode: `text2music` (from a caption and lyrics), `cover` (restyle a source track), `repaint` (regenerate a section), `extract` (isolate one instrument), `complete` (add parts to a track), or `demucs` (stem separation). Modes other than `text2music` need source audio as `src_audio_base64`.\n\nUnknown fields are passed through to the engine, so parameters newer than this schema still work. The required model is loaded automatically if a different one is selected, and downloaded if missing.", "operationId": "start_api_v1_generation_start_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationStartRequest" }, "examples": { "text2music": { "summary": "Text to music with ACE-Step", "value": { "task_type": "text2music", "prompt": "lofi hip hop, mellow piano, vinyl crackle, rainy night", "lyrics": "[Verse]\nRain on the window, coffee gone cold\n\n[Chorus]\nStay a while, stay a while", "audio_duration": 60 } }, "yue2": { "summary": "A song with YuE2", "value": { "engine": "yue2", "task_type": "text2music", "prompt": "indie pop, bright guitars, female vocal, upbeat", "lyrics": "[Verse]\nNeon fades along the lane\n\n[Chorus]\nLet the day come into view", "yue2_planning": "full", "yue2_max_seconds": 180 } }, "yue2_cover": { "summary": "A YuE2 cover from an analysed song", "value": { "engine": "yue2", "task_type": "cover", "prompt": "acoustic folk, warm guitar, male vocal", "lyrics": "[Verse]\nNeon fades along the lane\n\n[Chorus]\nLet the day come into view", "yue2_abc": "X:1 ... (the score from analyze-source)", "yue2_planning": "melody" } } } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartedResponse" }, "example": { "started": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "409": { "description": "Either a generation is already running — only one runs at a time — or no model is loaded. The detail says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/progress": { "get": { "tags": [ "Generation" ], "summary": "Poll generation progress", "description": "Status moves `idle` → `generating` → `complete`, or `error`. `step` and `total_steps` track diffusion progress; `message` names the current phase, which may be a model download or model switch before generation begins.", "operationId": "progress_api_v1_generation_progress_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateProgressResponse" }, "example": { "status": "generating", "message": "Generating...", "percent": 40, "step": 4, "total_steps": 10 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/result": { "get": { "tags": [ "Generation" ], "summary": "Get the last generation result", "description": "The most recent result, held until the next generation replaces it. `audio_paths` are server-side absolute paths — fetch each through `GET /api/v1/audio/download?path=...`, which is the only route permitted to read them.\n\nReturned fields vary by task type: stem separation reports one path per stem, while text2music reports musical metadata such as bpm and key.\n\nThis endpoint reports failure in the body rather than the status code: a 200 with `success: false` and an `error` string. Check `success`, not the status.", "operationId": "result_api_v1_generation_result_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateResultResponse" }, "example": { "success": true, "audio_paths": [ "C:\\...\\tmp\\output_0.wav" ], "seed": "12345", "duration": 120.0, "bpm": 128.0 } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/cancel": { "post": { "tags": [ "Generation" ], "summary": "Cancel the running generation", "description": "Stops the running generation or stem separation and reports `cancelled: true`, or `cancelled: false` when nothing is running. The run stops at its next checkpoint, such as the next diffusion step; a stem separation finishes its current pass and then discards it. Progress then returns to `idle` and the result's `error` is `Cancelled`.", "operationId": "cancel_api_v1_generation_cancel_post", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" }, "example": { "cancelled": true } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/analyze-source": { "post": { "tags": [ "Generation" ], "summary": "Analyse source audio", "description": "Inspects base64-encoded audio. With `engine` `acestep` (the default) it reports a style caption, tempo, length and musical key, plus lyrics from the lyrics transcriber add-on when it is downloaded. Without it, `lyrics_transcriber_missing` is set and the other fields are still filled. Use it to fill sensible defaults before a cover or repaint rather than guessing. With `engine` `yue2` it transcribes the song into the `score` and section-tagged `lyrics` that a YuE2 cover (`task_type` `cover`, `engine` `yue2`) needs. The request returns when analysis finishes; `GET /api/v1/generation/progress` reports progress meanwhile.\n\nThis endpoint reports failure in the body rather than the status code: a 200 with `success: false` and an `error` string. Check `success`, not the status.", "operationId": "analyze_source_api_v1_generation_analyze_source_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAudioRequest" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeSourceResponse" }, "example": { "success": true, "caption": "Dreamy synth pop", "lyrics": "Hello there\nHow are you?", "lyrics_found": true, "bpm": 128.0, "duration": 180.5, "key_scale": "A minor" } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/audio-hash": { "post": { "tags": [ "Generation" ], "summary": "Hash audio for deduplication", "description": "SHA-256 of the base64-decoded file bytes, used to recognise the same source track across requests. Pair it with `GET /api/v1/generation/extract-group` to reuse a previous separation instead of paying for it twice. Returns an empty hash if the input could not be decoded.", "operationId": "audio_hash_api_v1_generation_audio_hash_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioBase64Request" } } }, "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioHashResponse" }, "example": { "hash": "3b7f2c..." } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/generation/extract-group": { "get": { "tags": [ "Generation" ], "summary": "Find a previous extraction", "description": "Looks up an earlier stem separation or extraction for the same source audio, identified by the hash from `/api/v1/generation/audio-hash`. When `found` is true, the existing history entry already holds the stems and re-running is unnecessary.", "operationId": "extract_group_api_v1_generation_extract_group_get", "parameters": [ { "name": "source_hash", "in": "query", "required": true, "schema": { "type": "string", "description": "The `hash` from `POST /api/v1/generation/audio-hash` for the source track.", "title": "Source Hash" }, "description": "The `hash` from `POST /api/v1/generation/audio-hash` for the source track." }, { "name": "task_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Kind of earlier run to look for: `extract` (single-instrument extraction) or `demucs` (stem separation).", "default": "extract", "title": "Task Type" }, "description": "Kind of earlier run to look for: `extract` (single-instrument extraction) or `demucs` (stem separation)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractGroupResponse" }, "example": { "found": false } } } }, "401": { "description": "No API key, or the wrong one. Send `X-API-Key`, `Authorization: Bearer`, or `?api_key=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "The request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }, "/api/v1/audio/download": { "get": { "tags": [ "Audio" ], "summary": "Download an audio file", "description": "Streams a generated file with the right content type, so it can be used directly as an `