Music 01

This documentation is valid for the following list of our models:

• music-01

Try in Playground

An advanced AI model that generates diverse high-quality audio compositions by analyzing and reproducing musical patterns, rhythms, and vocal styles from the reference track. Refine the process using a text prompt.

How to Make a Call

Create AI/ML API Key

Step-by-Step Instructions

Generating an audio using this model involves sequentially calling two endpoints:

• The first one is for creating and sending a video generation task to the server (returns a generation ID).

• The second one is for requesting the generated video from the server using the generation ID received from the first endpoint.

Below, you can find two corresponding API schemas and examples for both endpoint calls.

---

If you want to learn how to call AI models via API from the very basics, feel free to use our Quickstart guide.

API Schemas

Upload a reference sample

This endpoint uploads a reference music piece to the server, analyzes it, and returns identifiers for the voice and/or instrumental patterns to use later.

post

Authorizations

AuthorizationstringRequired

Bearer key

Body

filestring · binaryRequired

Audio file local path, supports WAV and MP3 formats. The audio duration must be longer than 10s and no more than 10 minutes.

purposestring · enumRequired

1. If purpose is song:

• You need to upload a music file containing both acapella (vocals) and accompaniment.
• The acapella must be in singing form; normal speech is not supported.
• Outputs: voice_id and instrumental_id.

2. If purpose is voice:

• You need to upload a file containing only acapella in singing form (normal speech audio is not supported).
• Output: voice_id.

3. If purpose is instrumental:

• You need to upload a file containing only accompaniment.
• Output: instrumental_id.

Possible values:

Responses

default

application/json

voice_idstringOptional

The voice_id will only be returned when the purpose is song or voice.

Example: vocal-2025011003141025-d5ZEMxmp

instrumental_idstringOptional

The instrumental_id will only be returned when the purpose is song or instrumental.

Example: instrumental-2025011003141125-Akz9eWnD

default

{
  "voice_id": "vocal-2025011003141025-d5ZEMxmp",
  "instrumental_id": "instrumental-2025011003141125-Akz9eWnD",
  "base_resp": {
    "status_code": 1,
    "status_msg": "text"
  }
}

Generate music sample

This endpoint generates a new music piece based on the voice and/or instrumental pattern identifiers obtained from the first endpoint above. The generation can be completed in 50-60 seconds or take a bit more.

post

Authorizations

AuthorizationstringRequired

Bearer key

Body

lyricsstringRequired

Lyrics with optional formatting. You can use a newline to separate each line of lyrics. You can use two newlines to add a pause between lines. You can use double hash marks (##) at the beginning and end of the lyrics to add accompaniment. Maximum 600 characters.

Example: ##Swift and Boundless In the realm of innovation, where visions align, AIML API's the name, making tech shine. Intelligent solutions, breaking the mold, Swift inference power, bold and untold. ##

modelundefined · enumRequiredPossible values:

refer_voicestringOptional

voice_id. At least one of refer_voice or refer_instrumental is required. When only refer_voice is provided, the system can still output music data. The generated music will be an a cappella vocal hum that aligns with the provided refer_voice and the generated lyrics, without any instrumental accompaniment.

Example: vocal-2025010100000000-a0AAAaaa

refer_instrumentalstringOptional

instrumental_id. At least one of refer_voice or refer_instrumental is required. When only refer_instrumental is provided, the system can still output music data. The generated music will be a purely instrumental track that aligns with the provided refer_instrumental, without any vocals.

Example: instrumental-2025010100000000-Aaa0aAaA

Responses

default

application/json

analysis_infoany · nullableOptional

trace_idstringOptional

post/v2/generate/audio/minimax/generate

POST /v2/generate/audio/minimax/generate HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 420

{
  "lyrics": "##Swift and Boundless \n In the realm of innovation, where visions align, \n\nAIML API's the name, making tech shine. \nIntelligent solutions, breaking the mold, \n\nSwift inference power, bold and untold.\n##",
  "model": "music-01",
  "audio_setting": {
    "sample_rate": 16000,
    "bitrate": 32000,
    "format": "mp3"
  },
  "refer_voice": "vocal-2025010100000000-a0AAAaaa",
  "refer_instrumental": "instrumental-2025010100000000-Aaa0aAaA"
}

default

{
  "data": {
    "status": 1,
    "audio": "text"
  },
  "extra_info": {
    "audio_length": 1,
    "audio_size": 1,
    "audio_bitrate": 1,
    "audio_sample_rate": 1,
    "music_duration": 1,
    "music_sample_rate": 1,
    "music_channel": 1,
    "bitrate": 1,
    "music_size": 1
  },
  "analysis_info": null,
  "trace_id": "text",
  "base_resp": {
    "status_code": 1,
    "status_msg": "text"
  }
}

Quick Code Example

Here is an example of generation an audio file based on a sample and a prompt using the music model music-01.

Python

import requests

# Insert your AI/ML API key here:
aimlapi_key = "<YOUR_AIMLAPI_KEY>"

# Input data
audio_url = "https://tand-dev.github.io/audio-hosting/spinning-head-271171.mp3"
file_name = "spinning-head-271171.mp3"
purpose = "song"  # Possible values: 'song', 'voice', 'instrumental'


def upload_reference_file():
    """Download file from URL and upload it to AIML API"""

    url = "https://api.aimlapi.com/v2/generate/audio/minimax/upload"

    try:
        # Step 1: Download the file
        response = requests.get(audio_url)
        response.raise_for_status()

        # Step 2: Upload to AIML API
        payload = {"purpose": purpose}
        files = {"file": (file_name, response.content, "audio/mpeg")}
        headers = {"Authorization": f"Bearer {aimlapi_key}"}

        upload_response = requests.post(url, headers=headers, files=files, data=payload)
        upload_response.raise_for_status()

        data = upload_response.json()
        print("Upload successful:", data)
        return data  # return JSON with file ids

    except requests.exceptions.RequestException as error:
        print(f"Error during upload: {error}")
        return None


def generate_audio(voice_id=None, instrumental_id=None):
    """Send audio generation request and save result"""

    url = "https://api.aimlapi.com/v2/generate/audio/minimax/generate"
    lyrics = (
        "##Side by side, through thick and thin, \n\n"
        "With a laugh, we always win. \n\n"
        "Storms may come, but we stay true, \n\n"
        "Friends forever—me and you!##"
    )

    payload = {
        "refer_voice": voice_id,
        "refer_instrumental": instrumental_id,
        "lyrics": lyrics,
        "model": "music-01",
    }
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {aimlapi_key}",
    }

    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()

    audio_hex = response.json()["data"]["audio"]
    decoded_hex = bytes.fromhex(audio_hex)

    out_name = "generated_audio.mp3"
    with open(out_name, "wb") as f:
        f.write(decoded_hex)

    print(f"Generated audio saved as {out_name}")


def main():
    uploaded = upload_reference_file()
    if not uploaded:
        return

    # Extract IDs depending on purpose
    voice_id = uploaded.get("voice_id")
    instrumental_id = uploaded.get("instrumental_id")

    generate_audio(voice_id, instrumental_id)


if __name__ == "__main__":
    main()
    

JavaScript

import { writeFile } from "node:fs/promises";
import { Blob } from "node:buffer";

// Insert your AI/ML API key here:
const API_KEY = "<YOUR_AIMLAPI_KEY>";

// Input data
const AUDIO_URL = "https://tand-dev.github.io/audio-hosting/spinning-head-271171.mp3";
const FILE_NAME = "spinning-head-271171.mp3";
const PURPOSE = "song"; // Possible values: 'song', 'voice', 'instrumental'

// Download file from URL and upload it to AIML API
async function uploadReferenceFile() {
  const uploadUrl = "https://api.aimlapi.com/v2/generate/audio/minimax/upload";

  try {
    // Step 1: Download the file
    const response = await fetch(AUDIO_URL);
    if (!response.ok) throw new Error(`Failed to download file: ${response.status}`);

    const arrayBuffer = await response.arrayBuffer();
    const fileBlob = new Blob([arrayBuffer], { type: "audio/mpeg" });

    // Step 2: Upload to AIML API
    const formData = new FormData();
    formData.append("purpose", PURPOSE);
    formData.append("file", fileBlob, FILE_NAME);

    const uploadResponse = await fetch(uploadUrl, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        // Content-Type should not be set manually for FormData
      },
      body: formData,
    });

    if (!uploadResponse.ok) {
      const text = await uploadResponse.text();
      throw new Error(`Upload failed ${uploadResponse.status}: ${text}`);
    }

    const data = await uploadResponse.json();
    console.log("Upload successful:", data);
    return data; // JSON with file ids

  } catch (err) {
    console.error("Error during upload:", err.message);
    return null;
  }
}

// Send audio generation request and save result
async function generateAudio(voiceId = null, instrumentalId = null) {
  const url = "https://api.aimlapi.com/v2/generate/audio/minimax/generate";
  const lyrics = `
##Side by side, through thick and thin,
With a laugh, we always win.
Storms may come, but we stay true,
Friends forever—me and you!##
  `.trim();

  const payload = {
    refer_voice: voiceId,
    refer_instrumental: instrumentalId,
    lyrics,
    model: "music-01",
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const text = await res.text();
    throw new Error(`Generation failed ${res.status}: ${text}`);
  }

  const data = await res.json();
  const audioHex = data?.data?.audio;
  if (!audioHex) throw new Error("No audio hex in response");

  const audioBuffer = Buffer.from(audioHex, "hex");
  const outName = "generated_audio.mp3";
  await writeFile(outName, audioBuffer);
  console.log(`Generated audio saved as ${outName}`);
}

// Main function
async function main() {
  const uploaded = await uploadReferenceFile();
  if (!uploaded) return;

  // Extract IDs depending on purpose
  const voiceId = uploaded.voice_id;
  const instrumentalId = uploaded.instrumental_id;

  await generateAudio(voiceId, instrumentalId);
}

main();

Response

Upload successful: {'voice_id': 'vocal-2025082518145625-6XW9wCOF', 'instrumental_id': 'instrumental-2025082518145625-vCCEiiES', 'trace_id': '04fb6a8721abeee5b66edd452b4d0f33', 'base_resp': {'status_code': 0, 'status_msg': 'success'}}
Generated audio saved as generated_audio.mp3

Listen to the track we generated:

https://drive.google.com/file/d/1sKlPIK6kiYrp6__VhKkgGpr65e8qy2PU/view?usp=sharingdrive.google.com