Pixazo API→Models→Ace Step
Pixazo API→Models→Ace Step

Ace Step 1.5 XL API, Ace Step 1.5 API: Pricing, Documentation

by ACE Studio

View as Markdown

Ace Step 1.5 XL API, developers can generate high-quality custom soundtracks, background music, and audio content with ease. The API enables creators to produce professional-grade music compositions suitable for videos, games, podcasts, and multimedia projects without traditional music production expertise.

Get API Key
Ace Step Music API

Models Version

WELCOME BONUS

Get $5 Free Credit on First Payment

No strings attached — add funds and get $5 bonus instantly

Claim Your $5 →

Ace Step 1.5 XL API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour API subscription key

Submit Music Generation Request - ACE Step 1.5 XL API

Request Code

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/generate"

response = requests.post(
    BASE_URL,
    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

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

HeaderRequiredDefaultDescription
X-Webhook-URLYes (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-ModeNoterminalterminal — 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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring——Text description of the music to generate: genre, instruments, mood and vocal style (e.g. "Uplifting pop song with acoustic guitar and bright piano"). Prompts in 50+ languages are supported.
lyricsNostringempty (instrumental)Free text. Structure tags: [verse], [chorus], [bridge], [outro], [inst], [instrumental]Lyrics to be sung, with structure tags to control the song sections. Leave empty, or pass [inst] / [instrumental] as the whole value, to generate an instrumental track with no vocals.
durationNonumber3010-600 (seconds)Length of the generated audio in seconds. ACE-Step 1.5 XL supports 10 seconds up to 10 minutes; values above 600 are capped at 600.
seedNointeger-1-1 (random), or any non-negative integerFixed seed for reproducible output. Leave at -1 to let the model pick a random seed; pass a seed returned in a previous response to regenerate the same song.
bpmNonumberautoPositive number (beats per minute)Target tempo of the song. Omit this field to let the model choose a tempo that fits the prompt.
keyNostringautoMusical key name, e.g. "C major", "B minor"Musical key the song is written in. Omit this field to let the model choose the key.
time_signatureNostringautoTime signature, e.g. "4/4", "3/4", "6/8"Rhythmic time signature of the song. Omit this field to let the model choose.
batch_sizeNointeger11-4Number of song variations to generate from this prompt. Values above 4 are capped at 4. Each variation is returned as a separate entry in the songs array of the status response.
thinkingNobooleanfalsetrue, falseWhen true, the language model first plans the song (a chain-of-thought "blueprint" of structure and style) before generating. Improves structure and prompt adherence, at the cost of extra generation time.

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-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYOUR_SUBSCRIPTION_KEY

Response Handling

Common status codes.

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated media (R2 CDN)
output.media_typestringMIME type (audio/wav)
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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 API Pricing

Your request will cost $0.015 per song generation.
2. Ace Step 1.5

Ace Step 1.5 API Documentation

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

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour API subscription key

Generate Music - Ace step

Request Code

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": "",
  "duration": 120,
  "bpm": 140,
  "key": "E minor",
  "time_signature": "4/4",
  "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": "",
    "duration": 120,
    "bpm": 140,
    "key": "E minor",
    "time_signature": "4/4",
    "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: "",
  duration: 120,
  bpm: 140,
  key: "E minor",
  time_signature: "4/4",
  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": "",
    "duration": 120,
    "bpm": 140,
    "key": "E minor",
    "time_signature": "4/4",
    "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

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

HeaderRequiredDefaultDescription
X-Webhook-URLYes (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-ModeNoterminalterminal — 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

ParameterRequiredTypeDefaultAllowed values / rangeDescription
promptYesstring——Describes the overall musical style, genre, mood, instrumentation, and atmosphere.
lyricsNostringempty—Song lyrics controlling structure, sections, and vocal content. Use structure tags like [verse], [chorus], [bridge], [outro]. Leave empty for instrumental music. Default: empty
durationNointeger3010–600Target length of the generated track in seconds. The model supports 10–600 seconds (up to 10 minutes). Default: 30
bpmNointegerauto30–300Target tempo in beats per minute (30–300). Omit to let the model infer the tempo from the prompt. Default: auto
keyNostringauto—Musical key / scale, e.g. "C major", "B minor", "Am". Omit to let the model choose. Default: auto
time_signatureNostringauto2/4, 3/4, 4/4, 6/8Time signature of the track, e.g. "4/4", "3/4", "6/8". Omit to let the model choose. Default: auto
batch_sizeNointeger11–8Number of song variations to generate in one request (the model supports up to 8). Default: 1
thinkingNobooleanfalsetrue, falseIf true, the language model first reasons about the prompt and lyrics (chain-of-thought) before generating the audio codes — better musical coherence, slower generation. Default: false
seedNointeger-1—Random seed for reproducible output. Reuse the same seed with identical settings to reproduce a result; use -1 for a different result each time. Default: -1 (random)

Example Request

{
  "prompt": "A cinematic Hans Zimmer style orchestral piece, building tension with heavy percussion and brass, epic atmosphere",
  "lyrics": "",
  "duration": 120,
  "bpm": 140,
  "key": "E minor",
  "time_signature": "4/4",
  "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-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYOUR_SUBSCRIPTION_KEY

Response Handling

Common status codes.

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal 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

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated media (R2 CDN)
output.media_typestringMIME type of the output
created_atstringWhen request was created
completed_atstring|nullWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem 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 API Pricing

Your request will cost $0.015 per song generation.