Name: visoar ACE-Step 1.5 Song and Music Generator API
Brand: magicapi
SKU: api-magicapi-music-generation-api-visoar-ace-step-1-5
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎵 Song and Music Generator API (visoar ACE-Step 1.5)

![Song and Music Generator API (visoar ACE-Step 1.5) on api.market](https://blog.api.market/wp-content/uploads/2026/10/visoar__ace-step-1.5-cover-api-market.jpg)

## Overview
ACE-Step 1.5 generates music from a text description of the style and, optionally, song lyrics. Its developer describes it simply as music generation.

Describe the genre, instruments and mood in `caption`, and add `lyrics` with section tags such as [Verse] and [Chorus] for a song with vocals. Set the length with `duration` (1 to 600 seconds, default 90) and the number of variations with `batch_size` (1 to 4). Each request returns a list of audio URLs, one per variation.

## Features
- **Style prompt**: `caption` describes the genre, instruments and mood.
- **Lyrics**: optional `lyrics` with section tags such as [Verse] and [Chorus].
- **Length**: `duration` from 1 to 600 seconds (default 90).
- **Variations**: `batch_size` from 1 to 4 (default 1) generates several versions in one request.
- **Task limits**: `timeout_seconds` (30 to 7200, default 1800) sets the timeout for the generation task and `poll_interval` (1 to 30, default 3) the seconds between polling attempts.

## Use Cases
1. **Songs with vocals**: draft a full song from your own lyrics and a style description.
2. **Background music**: instrumental tracks for videos, podcasts, games and apps.
3. **Jingles and intros**: short pieces from a few seconds long.
4. **Exploring ideas**: several variations of the same brief in one request.

## Visual Examples
### Example Input
Caption: "An upbeat acoustic pop song with warm guitar, light percussion and clear vocals."

Lyrics:
```
[verse]
Morning light on the kitchen floor
Coffee warm and an open door
Pack a bag and a paper map
Leave the worries on the hallway mat

[chorus]
We go, we go, down the winding road
Singing loud with a lighter load
Every mile is a brand new day
We go, we go, and we find our way
```

Settings: `duration` 30, `batch_size` 1, `timeout_seconds` 600, `poll_interval` 3.

### Example Output
[Listen to the example output](https://blog.api.market/wp-content/uploads/2026/10/ace-step-1-5-output-gv2q1pha-api-market.mp3)

The generated 30-second track (MP3) for the caption and lyrics above.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `caption` | string | Yes |  |  | Music style prompt, for example genre, instruments and mood |
| `lyrics` | string | No | `""` |  | Optional lyrics with tags such as [Verse] and [Chorus] |
| `duration` | integer | No | `90` | 1 to 600 | Target duration in seconds |
| `batch_size` | integer | No | `1` | 1 to 4 | Number of variations to generate |
| `timeout_seconds` | integer | No | `1800` | 30 to 7200 | Timeout for the generation task, in seconds |
| `poll_interval` | number | No | `3` | 1 to 30 | Seconds between polling attempts |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.014 per API unit.
- **1 API unit = 1 request with up to 11 seconds of processing.** A request that runs longer is billed one more unit for each started 11-second block (for example, more than 11 and up to 22 seconds of processing is 2 units, $0.028).
- Longer `duration` values and more variations (`batch_size`) take longer to process and can cross into a second unit.
- **Example cost**: the example request (one 30-second song) took 6.2 seconds of processing, which fits in one 11-second block: 1 API unit, $0.014.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/music-generation-api-visoar-ace-step-1-5`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 2 seconds and an overall timeout of 1800 seconds (30 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/music-generation-api-visoar-ace-step-1-5/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "fd851baef553cb1656f4a05e8f2f8641672f10bc808718f5718b4b4bb2b07794",
    "input": {
      "lyrics": "[verse]\nMorning light on the kitchen floor\nCoffee warm and an open door\nPack a bag and a paper map\nLeave the worries on the hallway mat\n\n[chorus]\nWe go, we go, down the winding road\nSinging loud with a lighter load\nEvery mile is a brand new day\nWe go, we go, and we find our way",
      "caption": "An upbeat acoustic pop song with warm guitar, light percussion and clear vocals.",
      "duration": 30,
      "batch_size": 1,
      "poll_interval": 3,
      "timeout_seconds": 600
    }
  }'
```

Response (201 Created):
```json
{
  "id": "gv2q1pha7xrmr0d1f1t872e3e4",
  "version": "fd851baef553cb1656f4a05e8f2f8641672f10bc808718f5718b4b4bb2b07794",
  "status": "starting",
  "created_at": "2026-10-26T13:44:01.489Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/music-generation-api-visoar-ace-step-1-5/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "gv2q1pha7xrmr0d1f1t872e3e4",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/ace-step-1-5-output-gv2q1pha-api-market.mp3"
  ],
  "error": null,
  "created_at": "2026-10-26T13:44:01.489Z",
  "started_at": "2026-10-26T13:46:09.069Z",
  "completed_at": "2026-10-26T13:46:15.255Z"
}
```

`output` is a list of audio URLs (MP3 in the example), one per variation (`batch_size`).

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `caption` or a `duration` above 600.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/music-generation-api-visoar-ace-step-1-5";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "fd851baef553cb1656f4a05e8f2f8641672f10bc808718f5718b4b4bb2b07794", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 1800000;
  const pollInterval = 2000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 30 minutes");
}

createAndWaitForPrediction({
  "lyrics": "[verse]\nMorning light on the kitchen floor\nCoffee warm and an open door\nPack a bag and a paper map\nLeave the worries on the hallway mat\n\n[chorus]\nWe go, we go, down the winding road\nSinging loud with a lighter load\nEvery mile is a brand new day\nWe go, we go, and we find our way",
  "caption": "An upbeat acoustic pop song with warm guitar, light percussion and clear vocals.",
  "duration": 30,
  "batch_size": 1,
  "poll_interval": 3,
  "timeout_seconds": 600
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/music-generation-api-visoar-ace-step-1-5"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "fd851baef553cb1656f4a05e8f2f8641672f10bc808718f5718b4b4bb2b07794", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 1800
    poll_interval = 2
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 30 minutes")


print(create_and_wait_for_prediction({
    "lyrics": "[verse]\nMorning light on the kitchen floor\nCoffee warm and an open door\nPack a bag and a paper map\nLeave the worries on the hallway mat\n\n[chorus]\nWe go, we go, down the winding road\nSinging loud with a lighter load\nEvery mile is a brand new day\nWe go, we go, and we find our way",
    "caption": "An upbeat acoustic pop song with warm guitar, light percussion and clear vocals.",
    "duration": 30,
    "batch_size": 1,
    "poll_interval": 3,
    "timeout_seconds": 600
}))
```

## FAQ
- **Can I generate instrumental music?**
  - Yes. Leave `lyrics` empty (default) and describe the music in `caption`.
- **How long can a track be?**
  - `duration` goes from 1 to 600 seconds (10 minutes). The default is 90 seconds.
- **How do I format lyrics?**
  - Use plain lines with section tags such as [Verse] and [Chorus], separated by line breaks (`\n` in JSON), as in the example.
- **How many tracks does one request return?**
  - One per variation: `batch_size` from 1 to 4, returned as a list of URLs.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Generate songs from a style description and optional verse and chorus lyrics with ACE-Step 1.5, up to 10 minutes long. $0.014 per request.