# 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 submit request to receive a `POST` callback when the job completes — no polling required.

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### Example: enable webhook

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

### Callback Payload

Your endpoint receives a `POST application/json` with the same shape as the `GET /v2/requests/status/{request_id}` response. Example terminal callback (mode `terminal`):

```
{
  "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-xxxx-xxxx-xxxxxxxxxxxx/output.wav"
    ],
    "media_type": "audio/wav"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}
```

### Failure callback shape

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

### Delivery semantics

-   **terminal mode (default)** — exactly one `POST` when the request reaches a terminal status. No callback during `PROCESSING`.
-   **sync mode** — `POST` on every status poll (with delay capped at ~15s) plus a final `POST` at terminal status. Use when you want progress updates.
-   **Idempotency** — use `request_id` as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
-   **Response** — respond `200 OK` within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Generate Music

Parameter

Required

Type

Default

Allowed values / range

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

—

true, false

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 submit request to receive a `POST` callback when the job completes — no polling required.

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### Example: enable webhook

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

### Callback Payload

Your endpoint receives a `POST application/json` with the same shape as the `GET /v2/requests/status/{request_id}` response. Example terminal callback (mode `terminal`):

```
{
  "request_id": "ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ace-step-xl",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ace-step-xl_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.wav"
    ],
    "media_type": "audio/wav"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}
```

### Failure callback shape

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

### Delivery semantics

-   **terminal mode (default)** — exactly one `POST` when the request reaches a terminal status. No callback during `PROCESSING`.
-   **sync mode** — `POST` on every status poll (with delay capped at ~15s) plus a final `POST` at terminal status. Use when you want progress updates.
-   **Idempotency** — use `request_id` as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
-   **Response** — respond `200 OK` within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
-   **HTTPS required** — plain `http://` URLs are rejected.

## Request Parameters - Submit Music Generation Request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

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

lyrics

No

string

empty

—

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

duration

No

number

30

—

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

seed

No

integer

\-1

—

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

bpm

No

number

auto

—

Beats per minute. Default: auto

key

No

string

auto

—

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

time\_signature

No

string

auto

—

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

batch\_size

No

integer

1

—

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

thinking

No

boolean

false

true, false

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.