For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Audio generation

With MAX, you can deploy open-source music generation models on your local system or in the cloud and send inference requests with our REST API. This page explains how to use the v1/audio/speech endpoint to generate a song from a style caption and lyrics.

Endpoint

MAX serves audio generation on the v1/audio/speech endpoint. This endpoint currently only supports music generation. It does not support text-to-speech.

The v1/responses endpoint also supports music generation. Use that instead if it better fits your workflow.

Request fields

The following table lists fields that the speech endpoint accepts.

Field	Type	Default	Description
model	string	Required	ID of the model you send the request to.
input	string	Required	Lyrics to sing.
instructions	string	Required	The song description, covering genre, tempo, key, mood, vocal, and arrangement.
audio_duration	number	60	Upper bound on the song's length, in seconds. The model may produce songs shorter than the upper bound.
steps	integer	30	Denoising steps for the flow-matching stage.
guidance_scale	number	1.7	Classifier-free guidance. Raise it to follow the caption more literally.
seed	integer	0	Seed for the sampling and noise draws. The same seed and prompt reproduce the same song.
voice	string	Ignored	OpenAI's schema and Python SDK require it, but MAX has no voice catalog and ignores it.
response_format	string	wav	MAX supports only wav.

Response format

The response body is the audio itself. Its content type is audio/wav, and the format is 16-bit PCM at the model's own sample rate. Write the bytes to a file and play them.

Write the prompt

Song description

MiniMax-Music3 recognizes three song descriptors from its training:

• Global metadata: genre, tempo in BPM, key, mood, and production style.
• Vocal details: the singer's range and timbre, delivery, and effects.
• Arrangement: the instruments, and how they enter and leave across the song.

Therefore, your prompt should also use these descriptors. For example:

Global Metadata: dream pop, 92 BPM, A minor, wistful turning hopeful,
late-night drive, warm analog production with tape saturation.
Vocal Details: female lead, airy breathy timbre, intimate delivery, stacked
harmonies in the chorus, generous plate reverb.
Arrangement: shimmering electric guitar and analog pad, soft brushed drums,
round sub bass. Intro is guitar and pad alone, drums enter with the first
verse, the chorus opens wide with octave guitars, the bridge drops to pad and
voice, and the outro decays into tape hiss.

Lyrics and section tags

MiniMax-Music3 accepts lyrics that are organized with certain case-insensitive tags.

These include [intro], [verse], [pre-chorus], [chorus], [post-chorus], [bridge], [instrumental], [solo], and [outro]. Each tag needs its own line in the prompt.

Here are some example lyrics you can send with a request:

[intro]

[verse]
Headlights paint the empty road
Radio hums a song I almost know

[chorus]
Hold the night a little longer
Every mile makes the morning stronger

Quickstart

This quickstart shows you how to set up and run MiniMax-Music3 to generate a song from a caption and lyrics.

GPU required

To run MiniMax-Music3, your system must have a compatible GPU with sufficient GPU RAM. Music generation is GPU-intensive, and a full-length song takes several minutes to render. The checkpoint's weights don't all fit on a 24 GB card at once, but MAX loads and frees one stage at a time, so a 24 GB card is enough to serve it.

System requirements:

Mac

Linux

WSL

GPU

Set up your environment

Create a Python project to install our APIs and CLI tools:

pixi

1. If you don't have it, install pixi:

   curl -fsSL https://pixi.sh/install.sh | sh

   Then restart your terminal for the changes to take effect.

2. Create a project:

   pixi init audio-generation-quickstart \
     -c https://conda.modular.com/max-nightly/ -c conda-forge \
     && cd audio-generation-quickstart

   Tip: You can skip the -c options if you add these channels as defaults.

3. Install max with all dependencies (nightlyTo get the stable build, change the version in the website header.):

   pixi add max-all

4. Start the virtual environment:

   pixi shell

uv

1. If you don't have it, install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Then restart your terminal to make uv accessible.

2. Create a project:

   uv init audio-generation-quickstart && cd audio-generation-quickstart

3. Create and start a virtual environment:

   uv venv && source .venv/bin/activate

4. Install max with all dependencies (nightlyTo get the stable build, change the version in the website header.):

   uv add "max[all]" \
       --index https://whl.modular.com/nightly/simple/ \
       --prerelease allow

Serve your model

Use the max serve command to start a local model server:

max serve \
  --model MiniMaxAI/MiniMax-Music3

The endpoint is ready when you see this message printed in your terminal:

Server ready on http://0.0.0.0:8000 (Press CTRL+C to quit)

For a complete list of max CLI commands and options, refer to the MAX CLI reference.

Generate a song

The example below sends the song description and lyrics to the server. Then, it saves the WAV file that it returns.

Note that the first request after startup also compiles the model, so it takes several minutes longer than later requests.

Python

You can use OpenAI's Python client to interact with the music generation model. First, install the OpenAI SDK:

pixi

pixi add openai

uv

uv add openai

pip

pip install openai

conda

conda install openai

Then, create a client and make a request to the model:

generate-song.py

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

caption = (
    "Global Metadata: dream pop, 92 BPM, A minor, wistful turning hopeful, "
    "late-night drive, warm analog production with tape saturation. "
    "Vocal Details: female lead, airy breathy timbre, intimate delivery, "
    "stacked harmonies in the chorus, generous plate reverb. "
    "Arrangement: shimmering electric guitar and analog pad, soft brushed "
    "drums, round sub bass, chorus opens up with a wide guitar double."
)

lyrics = """[intro]

[verse]
Headlights paint the empty road
Radio hums a song I almost know

[chorus]
Hold the night a little longer
Every mile makes the morning stronger"""

response = client.audio.speech.create(
    model="MiniMaxAI/MiniMax-Music3",
    input=lyrics,
    instructions=caption,
    voice="",  # Required by OpenAI's schema, ignored by MAX.
    response_format="wav",
    extra_body={"audio_duration": 30, "seed": 1235},
)

response.write_to_file("song.wav")

Run the script to generate the song:

python generate-song.py

curl

Send a request to the v1/audio/speech endpoint and write the WAV body directly to a file:

curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -o song.wav \
  -d '{
    "model": "MiniMaxAI/MiniMax-Music3",
    "instructions": "Global Metadata: dream pop, 92 BPM, A minor, wistful turning hopeful, late-night drive, warm analog production with tape saturation. Vocal Details: female lead, airy breathy timbre, intimate delivery, stacked harmonies in the chorus, generous plate reverb. Arrangement: shimmering electric guitar and analog pad, soft brushed drums, round sub bass, chorus opens up with a wide guitar double.",
    "input": "[intro]\n\n[verse]\nHeadlights paint the empty road\nRadio hums a song I almost know\n\n[chorus]\nHold the night a little longer\nEvery mile makes the morning stronger",
    "audio_duration": 30,
    "seed": 1235
  }'

Next steps

Now that you can generate music, explore other inference capabilities and deployment options.

• Music generation: Renders a full-length song rather than a short clip.
• Image generation: Generate images from text prompts or transform existing images using the MAX v1/responses endpoint.
• Video generation: Generate videos from text prompts or animate existing images.