jameshuntercarter/Ace-Step-v1.5

1# ACE-Step API Client Documentation2 3**Language / 语言 / 言語:** [English](API.md) | [中文](../zh/API.md) | [日本語](../ja/API.md)4 5---6 7This service provides an HTTP-based asynchronous music generation API.8 9**Basic Workflow**:101. Call `POST /v1/music/generate` to submit a task and obtain a `job_id`.112. Call `GET /v1/jobs/{job_id}` to poll the task status until `status` is `succeeded` or `failed`.123. Download audio files via `GET /v1/audio?path=...` URLs returned in the result.13 14---15 16## Table of Contents17 18- [Task Status Description](#1-task-status-description)19- [Create Generation Task](#2-create-generation-task)20- [Query Task Results](#3-query-task-results)21- [Random Sample Generation](#4-random-sample-generation)22- [List Available Models](#5-list-available-models)23- [Download Audio Files](#6-download-audio-files)24- [Health Check](#7-health-check)25- [Environment Variables](#8-environment-variables)26 27---28 29## 1. Task Status Description30 31Task status (`status`) includes the following types:32 33- `queued`: Task has entered the queue and is waiting to be executed. You can check `queue_position` and `eta_seconds` at this time.34- `running`: Generation is in progress.35- `succeeded`: Generation succeeded, results are in the `result` field.36- `failed`: Generation failed, error information is in the `error` field.37 38---39 40## 2. Create Generation Task41 42### 2.1 API Definition43 44- **URL**: `/v1/music/generate`45- **Method**: `POST`46- **Content-Type**: `application/json`, `multipart/form-data`, or `application/x-www-form-urlencoded`47 48### 2.2 Request Parameters49 50#### Parameter Naming Convention51 52The API supports both **snake_case** and **camelCase** naming for most parameters. For example:53- `audio_duration` / `duration` / `audioDuration`54- `key_scale` / `keyscale` / `keyScale`55- `time_signature` / `timesignature` / `timeSignature`56- `sample_query` / `sampleQuery` / `description` / `desc`57- `use_format` / `useFormat` / `format`58 59Additionally, metadata can be passed in a nested object (`metas`, `metadata`, or `user_metadata`).60 61#### Method A: JSON Request (application/json)62 63Suitable for passing only text parameters, or referencing audio file paths that already exist on the server.64 65**Basic Parameters**:66 67| Parameter Name | Type | Default | Description |68| :--- | :--- | :--- | :--- |69| `caption` | string | `""` | Music description prompt |70| `lyrics` | string | `""` | Lyrics content |71| `thinking` | bool | `false` | Whether to use 5Hz LM to generate audio codes (lm-dit behavior). |72| `vocal_language` | string | `"en"` | Lyrics language (en, zh, ja, etc.) |73| `audio_format` | string | `"mp3"` | Output format (mp3, wav, flac) |74 75**Sample/Description Mode Parameters**:76 77| Parameter Name | Type | Default | Description |78| :--- | :--- | :--- | :--- |79| `sample_mode` | bool | `false` | Enable random sample generation mode (auto-generates caption/lyrics/metas via LM). |80| `sample_query` | string | `""` | Natural language description for sample generation (e.g., "a soft Bengali love song"). Aliases: `description`, `desc`. |81| `use_format` | bool | `false` | Use LM to enhance/format the provided caption and lyrics. Alias: `format`. |82 83**Multi-Model Support**:84 85| Parameter Name | Type | Default | Description |86| :--- | :--- | :--- | :--- |87| `model` | string | null | Select which DiT model to use (e.g., `"acestep-v15-turbo"`, `"acestep-v15-turbo-shift3"`). Use `/v1/models` to list available models. If not specified, uses the default model. |88 89**thinking Semantics (Important)**:90 91- `thinking=false`:92  - The server will **NOT** use 5Hz LM to generate `audio_code_string`.93  - DiT runs in **text2music** mode and **ignores** any provided `audio_code_string`.94- `thinking=true`:95  - The server will use 5Hz LM to generate `audio_code_string` (lm-dit behavior).96  - DiT runs with LM-generated codes for enhanced music quality.97 98**Metadata Auto-Completion (Conditional)**:99 100When `use_cot_caption=true` or `use_cot_language=true` or metadata fields are missing, the server may call 5Hz LM to fill the missing fields based on `caption`/`lyrics`:101 102- `bpm`103- `key_scale`104- `time_signature`105- `audio_duration`106 107User-provided values always win; LM only fills the fields that are empty/missing.108 109**Music Attribute Parameters**:110 111| Parameter Name | Type | Default | Description |112| :--- | :--- | :--- | :--- |113| `bpm` | int | null | Specify tempo (BPM), range 30-300 |114| `key_scale` | string | `""` | Key/scale (e.g., "C Major", "Am"). Aliases: `keyscale`, `keyScale` |115| `time_signature` | string | `""` | Time signature (2, 3, 4, 6 for 2/4, 3/4, 4/4, 6/8). Aliases: `timesignature`, `timeSignature` |116| `audio_duration` | float | null | Generation duration (seconds), range 10-600. Aliases: `duration`, `target_duration` |117 118**Audio Codes (Optional)**:119 120| Parameter Name | Type | Default | Description |121| :--- | :--- | :--- | :--- |122| `audio_code_string` | string or string[] | `""` | Audio semantic tokens (5Hz) for `llm_dit`. Alias: `audioCodeString` |123 124**Generation Control Parameters**:125 126| Parameter Name | Type | Default | Description |127| :--- | :--- | :--- | :--- |128| `inference_steps` | int | `8` | Number of inference steps. Turbo model: 1-20 (recommended 8). Base model: 1-200 (recommended 32-64). |129| `guidance_scale` | float | `7.0` | Prompt guidance coefficient. Only effective for base model. |130| `use_random_seed` | bool | `true` | Whether to use random seed |131| `seed` | int | `-1` | Specify seed (when use_random_seed=false) |132| `batch_size` | int | `2` | Batch generation count (max 8) |133 134**Advanced DiT Parameters**:135 136| Parameter Name | Type | Default | Description |137| :--- | :--- | :--- | :--- |138| `shift` | float | `3.0` | Timestep shift factor (range 1.0-5.0). Only effective for base models, not turbo models. |139| `infer_method` | string | `"ode"` | Diffusion inference method: `"ode"` (Euler, faster) or `"sde"` (stochastic). |140| `timesteps` | string | null | Custom timesteps as comma-separated values (e.g., `"0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0"`). Overrides `inference_steps` and `shift`. |141| `use_adg` | bool | `false` | Use Adaptive Dual Guidance (base model only) |142| `cfg_interval_start` | float | `0.0` | CFG application start ratio (0.0-1.0) |143| `cfg_interval_end` | float | `1.0` | CFG application end ratio (0.0-1.0) |144 145**5Hz LM Parameters (Optional, server-side)**:146 147These parameters control 5Hz LM sampling, used for metadata auto-completion and (when `thinking=true`) codes generation.148 149| Parameter Name | Type | Default | Description |150| :--- | :--- | :--- | :--- |151| `lm_model_path` | string | null | 5Hz LM checkpoint dir name (e.g. `acestep-5Hz-lm-0.6B`) |152| `lm_backend` | string | `"vllm"` | `vllm` or `pt` |153| `lm_temperature` | float | `0.85` | Sampling temperature |154| `lm_cfg_scale` | float | `2.5` | CFG scale (>1 enables CFG) |155| `lm_negative_prompt` | string | `"NO USER INPUT"` | Negative prompt used by CFG |156| `lm_top_k` | int | null | Top-k (0/null disables) |157| `lm_top_p` | float | `0.9` | Top-p (>=1 will be treated as disabled) |158| `lm_repetition_penalty` | float | `1.0` | Repetition penalty |159 160**LM CoT (Chain-of-Thought) Parameters**:161 162| Parameter Name | Type | Default | Description |163| :--- | :--- | :--- | :--- |164| `use_cot_caption` | bool | `true` | Let LM rewrite/enhance the input caption via CoT reasoning. Aliases: `cot_caption`, `cot-caption` |165| `use_cot_language` | bool | `true` | Let LM detect vocal language via CoT. Aliases: `cot_language`, `cot-language` |166| `constrained_decoding` | bool | `true` | Enable FSM-based constrained decoding for structured LM output. Aliases: `constrainedDecoding`, `constrained` |167| `constrained_decoding_debug` | bool | `false` | Enable debug logging for constrained decoding |168 169**Edit/Reference Audio Parameters** (requires absolute path on server):170 171| Parameter Name | Type | Default | Description |172| :--- | :--- | :--- | :--- |173| `reference_audio_path` | string | null | Reference audio path (Style Transfer) |174| `src_audio_path` | string | null | Source audio path (Repainting/Cover) |175| `task_type` | string | `"text2music"` | Task type: `text2music`, `cover`, `repaint`, `lego`, `extract`, `complete` |176| `instruction` | string | auto | Edit instruction (auto-generated based on task_type if not provided) |177| `repainting_start` | float | `0.0` | Repainting start time (seconds) |178| `repainting_end` | float | null | Repainting end time (seconds), -1 for end of audio |179| `audio_cover_strength` | float | `1.0` | Cover strength (0.0-1.0). Lower values (0.2) for style transfer. |180 181#### Method B: File Upload (multipart/form-data)182 183Use this when you need to upload local audio files as reference or source audio.184 185In addition to supporting all the above fields as Form Fields, the following file fields are also supported:186 187- `reference_audio`: (File) Upload reference audio file188- `src_audio`: (File) Upload source audio file189 190> **Note**: After uploading files, the corresponding `_path` parameters will be automatically ignored, and the system will use the temporary file path after upload.191 192### 2.3 Response Example193 194```json195{196  "job_id": "550e8400-e29b-41d4-a716-446655440000",197  "status": "queued",198  "queue_position": 1199}200```201 202### 2.4 Usage Examples (cURL)203 204**Basic JSON Method**:205 206```bash207curl -X POST http://localhost:8001/v1/music/generate \208  -H 'Content-Type: application/json' \209  -d '{210    "caption": "upbeat pop song",211    "lyrics": "Hello world",212    "inference_steps": 8213  }'214```215 216**With thinking=true (LM generates codes + fills missing metas)**:217 218```bash219curl -X POST http://localhost:8001/v1/music/generate \220  -H 'Content-Type: application/json' \221  -d '{222    "caption": "upbeat pop song",223    "lyrics": "Hello world",224    "thinking": true,225    "lm_temperature": 0.85,226    "lm_cfg_scale": 2.5227  }'228```229 230**Description-driven generation (sample_query)**:231 232```bash233curl -X POST http://localhost:8001/v1/music/generate \234  -H 'Content-Type: application/json' \235  -d '{236    "sample_query": "a soft Bengali love song for a quiet evening",237    "thinking": true238  }'239```240 241**With format enhancement (use_format=true)**:242 243```bash244curl -X POST http://localhost:8001/v1/music/generate \245  -H 'Content-Type: application/json' \246  -d '{247    "caption": "pop rock",248    "lyrics": "[Verse 1]\nWalking down the street...",249    "use_format": true,250    "thinking": true251  }'252```253 254**Select specific model**:255 256```bash257curl -X POST http://localhost:8001/v1/music/generate \258  -H 'Content-Type: application/json' \259  -d '{260    "caption": "electronic dance music",261    "model": "acestep-v15-turbo",262    "thinking": true263  }'264```265 266**With custom timesteps**:267 268```bash269curl -X POST http://localhost:8001/v1/music/generate \270  -H 'Content-Type: application/json' \271  -d '{272    "caption": "jazz piano trio",273    "timesteps": "0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0",274    "thinking": true275  }'276```277 278**With thinking=false (DiT only, but fill missing metas)**:279 280```bash281curl -X POST http://localhost:8001/v1/music/generate \282  -H 'Content-Type: application/json' \283  -d '{284    "caption": "slow emotional ballad",285    "lyrics": "...",286    "thinking": false,287    "bpm": 72288  }'289```290 291**File Upload Method**:292 293```bash294curl -X POST http://localhost:8001/v1/music/generate \295  -F "caption=remix this song" \296  -F "src_audio=@/path/to/local/song.mp3" \297  -F "task_type=repaint"298```299 300---301 302## 3. Query Task Results303 304### 3.1 API Definition305 306- **URL**: `/v1/jobs/{job_id}`307- **Method**: `GET`308 309### 3.2 Response Parameters310 311The response contains basic task information, queue status, and final results.312 313**Main Fields**:314 315- `status`: Current status316- `queue_position`: Current queue position (0 means running or completed)317- `eta_seconds`: Estimated remaining wait time (seconds)318- `avg_job_seconds`: Average job duration (for ETA estimation)319- `result`: Result object when successful320  - `audio_paths`: List of generated audio file URLs (use with `/v1/audio` endpoint)321  - `first_audio_path`: First audio path (URL)322  - `second_audio_path`: Second audio path (URL, if batch_size >= 2)323  - `generation_info`: Generation parameter details324  - `status_message`: Brief result description325  - `seed_value`: Comma-separated seed values used326  - `metas`: Complete metadata dict327  - `bpm`: Detected/used BPM328  - `duration`: Detected/used duration329  - `keyscale`: Detected/used key scale330  - `timesignature`: Detected/used time signature331  - `genres`: Detected genres (if available)332  - `lm_model`: Name of the LM model used333  - `dit_model`: Name of the DiT model used334- `error`: Error information when failed335 336### 3.3 Response Examples337 338**Queued**:339 340```json341{342  "job_id": "550e8400-e29b-41d4-a716-446655440000",343  "status": "queued",344  "created_at": 1700000000.0,345  "queue_position": 5,346  "eta_seconds": 25.0,347  "avg_job_seconds": 5.0,348  "result": null,349  "error": null350}351```352 353**Execution Successful**:354 355```json356{357  "job_id": "550e8400-e29b-41d4-a716-446655440000",358  "status": "succeeded",359  "created_at": 1700000000.0,360  "started_at": 1700000001.0,361  "finished_at": 1700000010.0,362  "queue_position": 0,363  "result": {364    "first_audio_path": "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3",365    "second_audio_path": "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fdef456.mp3",366    "audio_paths": [367      "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3",368      "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fdef456.mp3"369    ],370    "generation_info": "🎵 Generated 2 audios\n⏱️ Total: 8.5s\n🎲 Seeds: 12345,67890",371    "status_message": "✅ Generation completed successfully!",372    "seed_value": "12345,67890",373    "metas": {374      "bpm": 120,375      "duration": 30,376      "keyscale": "C Major",377      "timesignature": "4",378      "caption": "upbeat pop song with catchy melody"379    },380    "bpm": 120,381    "duration": 30,382    "keyscale": "C Major",383    "timesignature": "4",384    "genres": null,385    "lm_model": "acestep-5Hz-lm-0.6B",386    "dit_model": "acestep-v15-turbo"387  },388  "error": null389}390```391 392---393 394## 4. Random Sample Generation395 396### 4.1 API Definition397 398- **URL**: `/v1/music/random`399- **Method**: `POST`400 401This endpoint creates a sample-mode job that auto-generates caption, lyrics, and metadata via the 5Hz LM.402 403### 4.2 Request Parameters404 405| Parameter Name | Type | Default | Description |406| :--- | :--- | :--- | :--- |407| `thinking` | bool | `true` | Whether to also generate audio codes via LM |408 409### 4.3 Response Example410 411```json412{413  "job_id": "550e8400-e29b-41d4-a716-446655440000",414  "status": "queued",415  "queue_position": 1416}417```418 419### 4.4 Usage Example420 421```bash422curl -X POST http://localhost:8001/v1/music/random \423  -H 'Content-Type: application/json' \424  -d '{"thinking": true}'425```426 427---428 429## 5. List Available Models430 431### 5.1 API Definition432 433- **URL**: `/v1/models`434- **Method**: `GET`435 436Returns a list of available DiT models loaded on the server.437 438### 5.2 Response Example439 440```json441{442  "models": [443    {444      "name": "acestep-v15-turbo",445      "is_default": true446    },447    {448      "name": "acestep-v15-turbo-shift3",449      "is_default": false450    }451  ],452  "default_model": "acestep-v15-turbo"453}454```455 456### 5.3 Usage Example457 458```bash459curl http://localhost:8001/v1/models460```461 462---463 464## 6. Download Audio Files465 466### 6.1 API Definition467 468- **URL**: `/v1/audio`469- **Method**: `GET`470 471Download generated audio files by path.472 473### 6.2 Request Parameters474 475| Parameter Name | Type | Description |476| :--- | :--- | :--- |477| `path` | string | URL-encoded path to the audio file |478 479### 6.3 Usage Example480 481```bash482# Download using the URL from job result483curl "http://localhost:8001/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3" -o output.mp3484```485 486---487 488## 7. Health Check489 490### 7.1 API Definition491 492- **URL**: `/health`493- **Method**: `GET`494 495Returns service health status.496 497### 7.2 Response Example498 499```json500{501  "status": "ok",502  "service": "ACE-Step API",503  "version": "1.0"504}505```506 507---508 509## 8. Environment Variables510 511The API server can be configured using environment variables:512 513| Variable | Default | Description |514| :--- | :--- | :--- |515| `ACESTEP_API_HOST` | `127.0.0.1` | Server bind host |516| `ACESTEP_API_PORT` | `8001` | Server bind port |517| `ACESTEP_CONFIG_PATH` | `acestep-v15-turbo` | Primary DiT model path |518| `ACESTEP_CONFIG_PATH2` | (empty) | Secondary DiT model path (optional) |519| `ACESTEP_CONFIG_PATH3` | (empty) | Third DiT model path (optional) |520| `ACESTEP_DEVICE` | `auto` | Device for model loading |521| `ACESTEP_USE_FLASH_ATTENTION` | `true` | Enable flash attention |522| `ACESTEP_OFFLOAD_TO_CPU` | `false` | Offload models to CPU when idle |523| `ACESTEP_OFFLOAD_DIT_TO_CPU` | `false` | Offload DiT specifically to CPU |524| `ACESTEP_LM_MODEL_PATH` | `acestep-5Hz-lm-0.6B` | Default 5Hz LM model |525| `ACESTEP_LM_BACKEND` | `vllm` | LM backend (vllm or pt) |526| `ACESTEP_LM_DEVICE` | (same as ACESTEP_DEVICE) | Device for LM |527| `ACESTEP_LM_OFFLOAD_TO_CPU` | `false` | Offload LM to CPU |528| `ACESTEP_QUEUE_MAXSIZE` | `200` | Maximum queue size |529| `ACESTEP_QUEUE_WORKERS` | `1` | Number of queue workers |530| `ACESTEP_AVG_JOB_SECONDS` | `5.0` | Initial average job duration estimate |531| `ACESTEP_TMPDIR` | `.cache/acestep/tmp` | Temporary directory for files |532 533---534 535## Error Handling536 537**HTTP Status Codes**:538 539- `200`: Success540- `400`: Invalid request (bad JSON, missing fields)541- `404`: Job not found542- `415`: Unsupported Content-Type543- `429`: Server busy (queue is full)544- `500`: Internal server error545 546**Error Response Format**:547 548```json549{550  "detail": "Error message describing the issue"551}552```553 554---555 556## Best Practices557 5581. **Use `thinking=true`** for best quality results with LM-enhanced generation.559 5602. **Use `sample_query`/`description`** for quick generation from natural language descriptions.561 5623. **Use `use_format=true`** when you have caption/lyrics but want LM to enhance them.563 5644. **Poll job status** with reasonable intervals (e.g., every 1-2 seconds) to avoid overloading the server.565 5665. **Check `avg_job_seconds`** in the response to estimate wait times.567 5686. **Use multi-model support** by setting `ACESTEP_CONFIG_PATH2` and `ACESTEP_CONFIG_PATH3` environment variables, then select with the `model` parameter.569 5707. **For production**, always set proper Content-Type headers to avoid 415 errors.571