Ace Step 1.5 XL API, Ace Step 1.5 API - AI Music Generation APIs
by ACE Studio
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.

Models Version
Get $5 Free Credit on First Payment
No strings attached — add funds and get $5 bonus instantly
Ace Step 1.5 XL Text to Song (Lyrics to Song) API Documentation
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
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"
}
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
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.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) API Pricing
| Resolution | Price (USD) |
|---|---|
| Per Generation | $0.015 |
Ace Step 1.5 Text to Song (Lyrics to Song) API Documentation
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
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"
}
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
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Ace Step 1.5 Text to Song (Lyrics to Song) API Pricing
| Resolution | Price (USD) |
|---|---|
| All | $0.01 |