# Ace Step Music API

> Provider: **ACE Studio**
> Source: https://www.pixazo.ai/models/ace-step

Advanced music generation capabilities by ACE Studio. Leverage cutting-edge AI to compose original music across diverse genres and styles, enabling creators to produce custom soundtracks, background music, and audio content with ease.

## Ace Step 1.5

### Text to Song (Lyrics to Song)

## Base URL

```
https://gateway.pixazo.ai/ace-step/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Generate Music - Ace step

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/ace-step/v1/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
  "lyrics": "",
  "instrumental": true,
  "duration": 120,
  "bpm": 140,
  "infer_steps": 25,
  "guidance_scale": 7.5,
  "seed": 42
}
```

```
import requests

url = "https://gateway.pixazo.ai/ace-step/v1/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
    "lyrics": "",
    "instrumental": True,
    "duration": 120,
    "bpm": 140,
    "infer_steps": 25,
    "guidance_scale": 7.5,
    "seed": 42
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/ace-step/v1/generate';

const data = {
  prompt: "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
  lyrics: "",
  instrumental: true,
  duration: 120,
  bpm: 140,
  infer_steps: 25,
  guidance_scale: 7.5,
  seed: 42
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/ace-step/v1/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
    "lyrics": "",
    "instrumental": true,
    "duration": 120,
    "bpm": 140,
    "infer_steps": 25,
    "guidance_scale": 7.5,
    "seed": 42
  }'
```

## Output

```
{
  "request_id": "ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=ace-step&operation=generate-music)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Generate Music

Parameter

Required

Type

Description

prompt

Yes

string

Describes the overall musical style, genre, mood, instrumentation, and atmosphere.

lyrics

No

string

Temporal script of the song. Controls structure, sections, vocal style, instrumental breaks, and lyrical content.

instrumental

No

boolean

If true, generates instrumental-only music (no vocals).

duration

No

integer

Target duration in seconds.

bpm

No

integer

Target tempo in beats per minute.

infer\_steps

No

integer

Number of inference steps; higher values may increase quality but take longer.

guidance\_scale

No

float

Controls how strongly the model follows the prompt.

seed

No

integer

Used for reproducibility. Same seed and parameters produce similar outputs.

## Example Request

```
{
  "prompt": "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
  "lyrics": "",
  "instrumental": true,
  "duration": 120,
  "bpm": 140,
  "infer_steps": 25,
  "guidance_scale": 7.5,
  "seed": 42
}
```

## Response

```
{
  "request_id": "ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'ace-step' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ace-step",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "ace-step_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ace-step",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ace-step_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Ace Step 1.5 XL

### Text to Song (Lyrics to Song)

## Base URL

```
https://gateway.pixazo.ai/ace-step-xl/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Submit Music Generation Request - ACE Step 1.5 XL API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/ace-step-xl/v1/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Uplifting pop song with acoustic guitar and bright piano",
  "lyrics": "[verse]\nWoke up to a sky painted gold\n\n[chorus]\nYou are my sunshine after the rain",
  "duration": 60
}
```

```
import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://gateway.pixazo.ai/ace-step-xl/v1"

response = requests.post(
    f"{BASE_URL}/ace-step-xl/generate",
    headers={
        "Content-Type": "application/json",
        "Ocp-Apim-Subscription-Key": API_KEY
    },
    json={
  "prompt": "Uplifting pop song with acoustic guitar and bright piano",
  "lyrics": "[verse]\nWoke up to a sky painted gold\n\n[chorus]\nYou are my sunshine after the rain",
  "duration": 60
}
)

result = response.json()
print(result)
```

```
async function generateImage() {
  const response = await fetch(
    'https://gateway.pixazo.ai/ace-step-xl/v1/generate',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Ocp-Apim-Subscription-Key': process.env.API_KEY
      },
      body: JSON.stringify({
        prompt: 'A peaceful village in the mountains at sunset, ACE Step XL style'
      })
    }
  );
  
  const result = await response.json();
  console.log(result);
}

generateImage();
```

```
curl -v -X POST "https://gateway.pixazo.ai/ace-step-xl/v1/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
  "prompt": "Uplifting pop song with acoustic guitar and bright piano",
  "lyrics": "[verse]\nWoke up to a sky painted gold\n\n[chorus]\nYou are my sunshine after the rain",
  "duration": 60
}'
```

## Output

```
{
  "request_id": "ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=ace-step-xl&operation=generate)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Submit Music Generation Request

Parameter

Required

Type

Description

prompt

Yes

string

Genre, instruments, mood, vocals description (e.g., "Uplifting pop song with acoustic guitar, bright piano")

lyrics

No

string

Song lyrics with structure tags: \[verse\], \[chorus\], \[bridge\], \[outro\]. Default: empty

duration

No

number

Audio duration in seconds, max 600 (10 min). Default: 30

seed

No

integer

Fixed seed for reproducible output. Default: -1 (random)

bpm

No

number

Beats per minute. Default: auto

key

No

string

Musical key (e.g., "C major", "B minor"). Default: auto

time\_signature

No

string

Time signature (e.g., "4/4", "3/4"). Default: auto

batch\_size

No

integer

Number of variations to generate (1-4). Default: 1

thinking

No

boolean

LM "thinks" about prompt before generating for better quality. Default: false

## Example Request

```
{
  "prompt": "Uplifting pop song with acoustic guitar, bright piano, and energetic drums. Female vocals, 120 BPM, key of C major",
  "lyrics": "[verse]\nWoke up to a sky painted gold\nSoft light dancing on my window\n\n[chorus]\nYou are my sunshine after the rain\nRunning wild through every vein",
  "duration": 180,
  "seed": 42,
  "bpm": 120,
  "key": "C major",
  "time_signature": "4/4",
  "batch_size": 4,
  "thinking": true
}
```

## Response

```
{
  "request_id": "ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.01"
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'ace-step-xl' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ace-step-xl",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ace-step-xl_019d42ce-946d-7739-f812-6875c434cb790"
```

## Response (Completed)

```
{
  "request_id": "ace-step-xl_019d42ce-946d-7739-f812-6875c434cb790",
  "status": "COMPLETED",
  "model_id": "ace-step-xl",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ace-step-xl_019d42ce-946d-7739-f812-6875c434cb790/output_0.wav"
    ],
    "media_type": "audio/wav"
  },
  "created_at": "2026-03-31T07:32:03.749Z",
  "updated_at": "2026-03-31T07:32:20.000Z",
  "completed_at": "2026-03-31T07:32:20.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (audio/wav)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.