# Ace Step 1.5

>  Generate full songs from text prompts and lyrics—supports 50+ languages, 1000+ instruments/styles, BPM/key control, and upto 10 mins duration


## Overview

- **Endpoint**: `https://fal.run/fal-ai/ace-step-1.5`
- **Model ID**: `fal-ai/ace-step-1.5`
- **Category**: text-to-audio
- **Kind**: inference
**Tags**: text-to-audio, music, instruments



## Pricing

Your request will cost $0.0003 per output second. Thinking-enabled requests run at 2×.

For more details, see [fal.ai pricing](https://fal.ai/pricing).

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:


- **`prompt`** (`string`, _optional_):
  Music description/caption (style, instruments, mood). Max 512 characters. Default value: `""`
  - Default: `""`
  - Examples: "A melancholic Latin trap track built on a foundation of deep 808 sub-bass and crisp, rolling hi-hats from a drum machine. A somber synth pad provides an atmospheric backdrop for the emotional male lead vocal, which is treated with noticeable auto-tune and spacious reverb."

- **`lyrics`** (`string`, _optional_):
  Lyrics text with optional structure tags like [Verse], [Chorus]. Use '[Instrumental]' for instrumental music. Max 4096 characters. Default value: `""`
  - Default: `""`
  - Examples: "[Intro]\nYeah\nMe dicen ven, pero yo ya no quiero na'\n\n[Verse 1]\nNo hay más pa' ti ni de mami, ahora ves\nNo vengas con drama, lo sabes\n\n[Chorus]\nMe dicen ven, pero yo ya no quiero na'\nTe cansaste de estar pa' mí, ya no hay marcha atrás"

- **`duration`** (`float`, _optional_):
  Duration of the generated audio in seconds. Default value: `30`
  - Default: `30`
  - Range: `10` to `600`
  - Examples: 30, 60, 120

- **`thinking`** (`boolean`, _optional_):
  Use 5Hz LM to generate audio codes for enhanced quality via Chain-of-Thought reasoning. Set to False for faster DiT-only generation. Default value: `true`
  - Default: `true`

- **`bpm`** (`integer`, _optional_):
  Beats per minute. If not specified, will be auto-detected.
  - Range: `30` to `300`
  - Examples: 92, 120, 140

- **`key_scale`** (`string`, _optional_):
  Musical key (e.g., 'C Major', 'Am'). If not specified, will be auto-detected. Default value: `""`
  - Default: `""`

- **`time_signature`** (`TimeSignatureEnum`, _optional_):
  Time signature: 2 for 2/4, 3 for 3/4, 4 for 4/4, 6 for 6/8. Default value: `""`
  - Default: `""`
  - Options: `""`, `"2"`, `"3"`, `"4"`, `"6"`
  - Examples: "4"

- **`vocal_language`** (`string`, _optional_):
  Vocal language code (e.g., 'en', 'zh', 'ja', 'ko'). Use 'unknown' for auto-detection. Default value: `"unknown"`
  - Default: `"unknown"`
  - Examples: "en", "es", "zh", "ja"

- **`num_inference_steps`** (`integer`, _optional_):
  The number of inference steps to perform. Turbo: 8 recommended. Base: 32-64 recommended. Default value: `8`
  - Default: `8`
  - Range: `1` to `100`

- **`guidance_scale`** (`float`, _optional_):
  Classifier-free guidance scale. Only applies to base models, ignored by turbo. Default value: `7`
  - Default: `7`
  - Range: `1` to `20`

- **`shift`** (`float`, _optional_):
  Timestep shift factor. 3.0 recommended for turbo models. Default value: `3`
  - Default: `3`
  - Range: `1` to `5`

- **`seed`** (`integer`, _optional_):
  Random seed for reproducibility.

- **`num_outputs`** (`integer`, _optional_):
  The number of audio samples to generate. Default value: `1`
  - Default: `1`
  - Range: `1` to `4`

- **`infer_method`** (`InferMethodEnum`, _optional_):
  Diffusion inference method. 'ode' (Euler) is faster and deterministic. 'sde' (stochastic) may produce varied results. Default value: `"ode"`
  - Default: `"ode"`
  - Options: `"ode"`, `"sde"`

- **`lm_temperature`** (`float`, _optional_):
  LM sampling temperature. Higher values produce more creative/diverse output. Default value: `0.85`
  - Default: `0.85`
  - Range: `0` to `2`

- **`lm_cfg_scale`** (`float`, _optional_):
  LM classifier-free guidance scale. WARNING: Values >1.0 trigger slow step-by-step CFG generation (~10x slower). Keep at 1.0 for fast inference. Default value: `1`
  - Default: `1`
  - Range: `1` to `10`

- **`lm_negative_prompt`** (`string`, _optional_):
  Negative prompt for LM guidance. Helps avoid unwanted characteristics. Default value: `"NO USER INPUT"`
  - Default: `"NO USER INPUT"`

- **`use_constrained_decoding`** (`boolean`, _optional_):
  Enable constrained decoding for structured LM output (more reliable metadata parsing). Default value: `true`
  - Default: `true`



**Required Parameters Example**:

```json
{}
```

**Full Example**:

```json
{
  "prompt": "A melancholic Latin trap track built on a foundation of deep 808 sub-bass and crisp, rolling hi-hats from a drum machine. A somber synth pad provides an atmospheric backdrop for the emotional male lead vocal, which is treated with noticeable auto-tune and spacious reverb.",
  "lyrics": "[Intro]\nYeah\nMe dicen ven, pero yo ya no quiero na'\n\n[Verse 1]\nNo hay más pa' ti ni de mami, ahora ves\nNo vengas con drama, lo sabes\n\n[Chorus]\nMe dicen ven, pero yo ya no quiero na'\nTe cansaste de estar pa' mí, ya no hay marcha atrás",
  "duration": 30,
  "thinking": true,
  "bpm": 92,
  "time_signature": "4",
  "vocal_language": "en",
  "num_inference_steps": 8,
  "guidance_scale": 7,
  "shift": 3,
  "num_outputs": 1,
  "infer_method": "ode",
  "lm_temperature": 0.85,
  "lm_cfg_scale": 1,
  "lm_negative_prompt": "NO USER INPUT",
  "use_constrained_decoding": true
}
```


### Output Schema

The API returns the following output format:

- **`audio`** (`Audio`, _required_):
  Preview of the first generated audio file for quick playback
  - Examples: {"file_size":1995603,"content_type":"audio/flac","file_name":"b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac","url":"https://fal.media/files/panda/K0Fvk-Qh5ujibopcCqX_a_b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac"}

- **`audios`** (`list<GeneratedAudio>`, _required_):
  List of generated audio files
  - Array of GeneratedAudio

- **`bpm`** (`integer`, _optional_):
  Detected/used BPM
  - Examples: 120

- **`duration`** (`float`, _optional_):
  Audio duration in seconds
  - Examples: 30

- **`key_scale`** (`string`, _optional_):
  Detected/used key

- **`time_signature`** (`string`, _optional_):
  Detected/used time signature
  - Examples: "4"

- **`enhanced_prompt`** (`string`, _optional_):
  LM-enhanced prompt (if thinking=True)



**Example Response**:

```json
{
  "audio": {
    "file_size": 1995603,
    "content_type": "audio/flac",
    "file_name": "b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac",
    "url": "https://fal.media/files/panda/K0Fvk-Qh5ujibopcCqX_a_b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac"
  },
  "audios": [
    {
      "audio": {
        "file_size": 1995603,
        "content_type": "audio/flac",
        "file_name": "b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac",
        "url": "https://fal.media/files/panda/K0Fvk-Qh5ujibopcCqX_a_b44bec6a-c1e8-56fc-bbe5-44f9472ae8e6.flac"
      },
      "seed": 42
    }
  ],
  "bpm": 120,
  "duration": 30,
  "time_signature": "4"
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/ace-step-1.5 \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

### Python

Ensure you have the Python client installed:

```bash
pip install fal-client
```

Then use the API client to make requests:

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/ace-step-1.5",
    arguments={},
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

### JavaScript

Ensure you have the JavaScript client installed:

```bash
npm install --save @fal-ai/client
```

Then use the API client to make requests:

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/ace-step-1.5", {
  input: {},
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```


## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/fal-ai/ace-step-1.5)
- [API Documentation](https://fal.ai/models/fal-ai/ace-step-1.5/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ace-step-1.5)

### fal.ai Platform

- [Platform Documentation](https://fal.ai/docs/documentation)
- [Python Client](https://fal.ai/docs/api-reference/client-libraries/python)
- [JavaScript Client](https://fal.ai/docs/api-reference/client-libraries/javascript)

### Other agent-readable surfaces

This file covers one model. To find anything else:

- [Platform overview](https://fal.ai/llms.txt): Entry points and representative endpoint IDs
- [Documentation index](https://fal.ai/docs/llms.txt): Every documentation page
- [Full documentation text](https://fal.ai/docs/llms-full.txt): The whole documentation inlined
- Any other model: `https://fal.ai/models/<endpoint-id>/llms.txt`