Skip to main content
ModelRunner
ace-studio avatar

ACE-Step API

ace-studio/ace-step

Generate full songs or instrumental music from genre tags and optional lyrics, with duration you control up to 4 minutes.

0.0002 per second of output video
OpenAPI

Model Input

Input

Comma-separated genre, mood, and instrument tags that define the musical style (e.g. 'lofi, hiphop, chill' or 'epic orchestral, cinematic'). This is the style control, not a prose prompt.

Optional song lyrics. Use section markers like [verse], [chorus], and [bridge] to structure a sung track. Leave empty or set to [inst]/[instrumental] for an instrumental piece.

Min: 5 - Max: 240

Length of the generated audio in seconds.

Additional Settings

Customize your input with more control.

Min: 3 - Max: 60

Number of generation steps. More steps can improve quality at the cost of speed.

Random seed for reproducible generation. Leave empty for a random result.

Diffusion sampler used during generation.

Guidance algorithm. apg is the most stable default; cfg and cfg_star are alternatives.

Min: -100 - Max: 100

Controls artifact reduction granularity during generation.

Min: 0 - Max: 1

Fraction of the generation over which guidance is applied.

Min: 0 - Max: 1

How much the guidance scale decays across the guidance interval.

Min: 0 - Max: 200

Classifier-free guidance scale; higher values follow the tags and lyrics more strictly.

Min: 0 - Max: 200

Floor that the guidance scale decays toward over the guidance interval.

Min: 0 - Max: 10

How strongly generation adheres to the genre tags.

Min: 0 - Max: 10

How strongly generation adheres to the provided lyrics.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

Loading
Generated in 9.42 seconds
Logs (1 lines)

Model Example Requests

Examples

ACE-Step API

ACE-Step is a music AI model by ace-studio. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.0002 per second of audio.

POST https://queue.modelrunner.run/ace-studio/ace-step

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/ace-studio/ace-step \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": "lofi, chill, piano",
    "lyrics": "",
    "duration": 8,
    "scheduler": "euler",
    "guidance_type": "apg",
    "guidance_scale": 15,
    "number_of_steps": 27,
    "granularity_scale": 10,
    "guidance_interval": 0.5,
    "tag_guidance_scale": 5,
    "lyric_guidance_scale": 1.5,
    "minimum_guidance_scale": 3,
    "guidance_interval_decay": 0,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/ace-studio/ace-step/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/ace-studio/ace-step/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("ace-studio/ace-step", {
  input: {
    "tags": "lofi, chill, piano",
    "lyrics": "",
    "duration": 8,
    "scheduler": "euler",
    "guidance_type": "apg",
    "guidance_scale": 15,
    "number_of_steps": 27,
    "granularity_scale": 10,
    "guidance_interval": 0.5,
    "tag_guidance_scale": 5,
    "lyric_guidance_scale": 1.5,
    "minimum_guidance_scale": 3,
    "guidance_interval_decay": 0
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/ace-studio/ace-step",
    headers=headers,
    json={
      "tags": "lofi, chill, piano",
      "lyrics": "",
      "duration": 8,
      "scheduler": "euler",
      "guidance_type": "apg",
      "guidance_scale": 15,
      "number_of_steps": 27,
      "granularity_scale": 10,
      "guidance_interval": 0.5,
      "tag_guidance_scale": 5,
      "lyric_guidance_scale": 1.5,
      "minimum_guidance_scale": 3,
      "guidance_interval_decay": 0
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
tagsstringyesComma-separated genre, mood, and instrument tags that define the musical style (e.g. 'lofi, hiphop, chill' or 'epic orchestral, cinematic'). This is the style control, not a prose prompt.
lyricsstringnoOptional song lyrics. Use section markers like [verse], [chorus], and [bridge] to structure a sung track. Leave empty or set to [inst]/[instrumental] for an instrumental piece. Default: "".
durationnumbernoLength of the generated audio in seconds. Default: 60.
number_of_stepsintegernoNumber of generation steps. More steps can improve quality at the cost of speed. Default: 27.
seedintegernoRandom seed for reproducible generation. Leave empty for a random result.
schedulerenumnoDiffusion sampler used during generation. Default: "euler".
guidance_typeenumnoGuidance algorithm. apg is the most stable default; cfg and cfg_star are alternatives. Default: "apg".
granularity_scaleintegernoControls artifact reduction granularity during generation. Default: 10.
guidance_intervalnumbernoFraction of the generation over which guidance is applied. Default: 0.5.
guidance_interval_decaynumbernoHow much the guidance scale decays across the guidance interval. Default: 0.
guidance_scalenumbernoClassifier-free guidance scale; higher values follow the tags and lyrics more strictly. Default: 15.
minimum_guidance_scalenumbernoFloor that the guidance scale decays toward over the guidance interval. Default: 3.
tag_guidance_scalenumbernoHow strongly generation adheres to the genre tags. Default: 5.
lyric_guidance_scalenumbernoHow strongly generation adheres to the provided lyrics. Default: 1.5.

Machine-readable: OpenAPI schema · llms.txt

Use ACE-Step from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and ACE-Step becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint ace-studio/ace-step.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run ace-studio/ace-step on ModelRunner to generate music”. MCP setup guide.

Model Details

Model Details

ACE-Step turns a short list of genre tags — and optional lyrics — into a complete, hosted music track. Describe the style you want with comma-separated tags (`tags`, e.g. "lofi, hiphop, chill" or "epic orchestral, cinematic"), add lyrics with `[verse]`/`[chorus]` markup to get a sung vocal track, or leave lyrics empty for a fully instrumental piece. Its strength is fast, controllable song generation: you set the duration in seconds and steer the result with genre tags rather than a long prose prompt, and the model returns a finished audio file ready to download.

## Best for - Generating complete songs with vocals from lyrics plus a genre/style description - Producing instrumental backing tracks, beats, and loops from genre tags alone - Background music beds for video, games, and podcasts in a specific style - Quickly auditioning musical ideas across genres before a full production session

## Choose another model when - You need spoken narration or voiceover rather than sung music — use a text-to-speech model - You want isolated one-off sound effects, foley, or ambience instead of a music track — use a text-to-audio sound-effects model - You need to extend, remix, or inpaint an existing audio clip — use an audio-to-audio model

## Tips - `tags` is the style control (not a prose prompt): pass comma-separated genres, moods, and instruments, e.g. "pop, acoustic, guitar" or "drum and bass, energetic, synth". - Leave `lyrics` empty (or set it to `[inst]`) for an instrumental track. For vocals, structure lyrics with section markers like `[verse]`, `[chorus]`, and `[bridge]`, one line per lyric line. - `duration` is in seconds (5–240, default 60). Longer durations cost proportionally more, since pricing is per second of generated audio.

## Advanced Configuration - `scheduler` (default `euler`): the diffusion sampler — `euler` or `heun`. `heun` can refine quality at the cost of speed. Configured via the API. - `guidance_type` (default `apg`): the guidance algorithm — `cfg`, `apg`, or `cfg_star`. `apg` (the default) generally gives the most stable results. Configured via the API. - `tag_guidance_scale` (default 5) and `lyric_guidance_scale` (default 1.5): how strongly generation adheres to the genre tags versus the lyrics. Raise to follow the input more strictly. Configured via the API.

To run via the ModelRunner JavaScript client: ```js import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("ace-studio/ace-step", { input: { tags: "lofi, hiphop, chill", lyrics: "[verse]\ncity lights and quiet streets\n[chorus]\nslow it down, feel the beat", duration: 60, }, }); ```