# ACE-Step

> ACE-Step open music foundation model via Replicate. Generates up to 4 minutes of music with vocals from style tags and structured lyrics, with full control over steps, scheduler and guidance.

- **Provider**: replicate
- **Model ID**: lucataco/ace-step
- **Category**: music_generation
- **Credits**: from 16 for the default configuration — varies by input, see Pricing
- **Pricing Type**: formula

## API Endpoint

Base URL: https://api.core.today/v1

### Create Prediction
POST /predictions

### Get Status
GET /predictions/{job_id}

### Cancel
DELETE /predictions/{job_id}

## Authentication

Header: `X-API-Key: YOUR_API_KEY`

## Input Parameters

- `tags` (string, **required**): Text prompts to guide music generation, e.g. 'synth-pop, electronic, 128 BPM, energetic'.
- `granularity_scale` (number, optional): Omega scale for APG guidance (-100 to 100). (Default: `10`; Range: min: -100, max: 100)
- `tag_guidance_scale` (number, optional): Guidance scale for tags (0-10). (Default: `0`; Range: min: 0, max: 10)
- `guidance_interval` (number, optional): Guidance interval (0-1). (Default: `0.5`; Range: min: 0, max: 1)
- `seed` (integer, optional): Random seed. -1 randomizes. (Default: `-1`)
- `min_guidance_scale` (number, optional): Minimum guidance scale (0-100). (Default: `3`; Range: min: 0, max: 100)
- `guidance_type` (string, optional): Guidance type for CFG. (Default: `apg`; Options: `apg`, `cfg`, `cfg_star`)
- `guidance_interval_decay` (number, optional): Guidance interval decay (0-1). (Default: `0`; Range: min: 0, max: 1)
- `duration` (number, optional): Duration of the generated audio in seconds (1-240). (Default: `60`; Range: min: 1, max: 240)
- `scheduler` (string, optional): Scheduler type. (Default: `euler`; Options: `euler`, `heun`)
- `guidance_scale` (number, optional): Overall guidance scale (0-30). (Default: `15`; Range: min: 0, max: 30)
- `number_of_steps` (integer, optional): Number of inference steps (10-200). (Default: `60`; Range: min: 10, max: 200)
- `lyrics` (string, optional): Lyrics for the music. Use [verse], [chorus], and [bridge] to separate parts. Use [instrumental] or [inst] for instrumental music.
- `lyric_guidance_scale` (number, optional): Guidance scale for lyrics (0-10). (Default: `0`; Range: min: 0, max: 10)

## Example Request

```json
{
  "model": "lucataco/ace-step",
  "input": {
    "duration": 60,
    "lyrics": "[verse]\nWoke up in a city that's always alive\nNeon lights they shimmer they thrive\n\n[chorus]\nOh we ride the night\nelectric hearts alight",
    "tags": "synth-pop, electronic, pop, synthesizer, drums, bass, piano, 128 BPM, energetic, uplifting, modern"
  }
}
```

## Response Format

```json
{
  "job_id": "abc123",
  "status": "pending",
  "provider": "replicate",
  "model": "lucataco/ace-step",
  "created_at": "2026-01-01T00:00:00Z",
  "result": null,
  "error": null,
  "credits_used": null
}
```

Status values: `pending`, `processing`, `completed`, `failed`, `cancelled`

When the job is `completed`, `result` holds the output URL(s) or data and `credits_used` the net credits charged. When it is `failed`, `error` and `error_code` say why and the charge is refunded.

## Usage Flow

1. POST /predictions with model and input → receive job_id
2. Poll GET /predictions/{job_id} until status is `completed` or `failed`
3. Result contains output URL(s) or data

## Pricing

- Formula: `(base + rate * duration) * number_of_steps / 60` credits
  - `base`: 2.72
  - `duration`: the `duration` input (default 60)
  - `number_of_steps`: the `number_of_steps` input (default 60)
  - `rate`: 0.2135

Default configuration: 16 credits.

These are list prices. The amount charged is rounded, and large charges are discounted progressively. `POST /predictions/estimate` with the same `model` and `input` returns the charge for that input without creating a job (an estimate when the price depends on the output).

## Output Type

url

## Tags

music-generation, text-to-music, lyrics-to-song, open-source, ace-step

## Documentation

https://replicate.com/lucataco/ace-step