> ## Documentation Index
> Fetch the complete documentation index at: https://platform.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-host MiniMax Music 3

> Serve MiniMax Music 3 with a pinned SGLang-Omni runtime and generate songs through the Speech API.

MiniMax Music 3 generates complete songs with vocals and accompaniment from lyrics and a music description. This page deploys an HTTP service on NVIDIA CUDA GPUs with SGLang-Omni; it is a **self-hosted server deployment**, not a consumer-device local-running guide.

<Note>
  The model card describes native generation of songs up to approximately five minutes. SGLang-Omni accepts at most `9,000` acoustic frames at 25 frames per second, which is a six-minute request cap. The framework limit is not an additional minute of validated model capability. Keep `max_new_tokens` at or below `7,500` when you need to remain within the model's documented five-minute scope.
</Note>

## Deployment status

| Item                      | Baseline                                                                                                                                        |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| Deployment status         | Official stability level not published; use this as a reference deployment until MiniMax publishes a complete hardware and performance baseline |
| Verified API path         | Lyrics and music description to a non-streaming WAV response through `POST /v1/audio/speech`                                                    |
| Model                     | `MiniMaxAI/MiniMax-Music3`                                                                                                                      |
| Model revision            | `fbdf52fbaaca799592917417eb05f1899f1255ec`                                                                                                      |
| Serving framework         | `sglang-omni==0.1.3` ([tag `v0.1.3`](https://github.com/sgl-project/sglang-omni/tree/v0.1.3))                                                   |
| Python                    | 3.10–3.12; this guide uses 3.12                                                                                                                 |
| Documentation review date | August 26, 2026                                                                                                                                 |

The pinned model revision and framework version make the commands repeatable. They do not mean that MiniMax has benchmarked every compatible GPU, driver, or operating-system combination.

## Hardware baseline

SGLang-Omni publishes one reference-output configuration and two placement modes. It does not publish Music 3 peak VRAM, minimum GPU memory, host RAM, minimum driver, generation latency, or real-time factor.

| Configuration       | GPU placement                                                 | Reference workload                                              | Peak VRAM     | Host RAM      | Performance   | Status                                      |
| :------------------ | :------------------------------------------------------------ | :-------------------------------------------------------------- | :------------ | :------------ | :------------ | :------------------------------------------ |
| 1 × NVIDIA H200     | Autoregressive and acoustic stages colocated                  | Five 30-second-or-shorter reference clips with default settings | Not published | Not published | Not published | Upstream reference                          |
| 2 × NVIDIA CUDA GPU | Autoregressive stage on GPU 0; DiT and audio decoder on GPU 1 | Not published                                                   | Not published | Not published | Not published | Placement supported; capacity not validated |

The single-GPU command does not imply that every CUDA GPU has enough memory. Validate a short request on your exact hardware before accepting production traffic. The model repository currently reports approximately 57.4 GB of files; reserve additional disk for the Python environment, download metadata, and temporary files.

## Quickstart

### Install the pinned runtime

Use a clean Linux environment with an NVIDIA CUDA GPU. SGLang-Omni `0.1.3` pins CUDA 13 runtime packages, PyTorch `2.11.0`, and SGLang `0.5.16`. The upstream project has not published an exact minimum NVIDIA driver for this Music 3 configuration; confirm that your driver supports the installed CUDA runtime.

```bash theme={null}
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install --prerelease=allow "sglang-omni==0.1.3"

python -c "import sglang_omni, torch; print(sglang_omni.__version__, torch.__version__, torch.cuda.is_available())"
```

The last value must be `True` before you continue. For UCX and CUDA build prerequisites, see the [SGLang-Omni installation guide](https://sgl-project.github.io/sglang-omni/get_started/installation.html).

### Download the pinned weights

```bash theme={null}
export MUSIC3_MODEL_DIR=/data/models/MiniMax-Music3-fbdf52f

hf download MiniMaxAI/MiniMax-Music3 \
  --revision fbdf52fbaaca799592917417eb05f1899f1255ec \
  --local-dir "$MUSIC3_MODEL_DIR"
```

### Start the service

The default quickstart listens only on the loopback interface. Keep this terminal running:

```bash theme={null}
CUDA_VISIBLE_DEVICES=0 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000
```

### Check service health

Run these commands in another terminal:

```bash theme={null}
curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/models
```

`/health` should return HTTP `200` with a healthy, running status. `/v1/models` should include `MiniMaxAI/MiniMax-Music3`.

### Generate and verify a song

```bash theme={null}
curl --fail-with-body -X POST http://127.0.0.1:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-Music3",
    "input": "[Verse]\nMorning light across the floor\nThe quiet streets begin to wake\n[Chorus]\nStep into another day\nLet the music lead the way",
    "instructions": "Warm acoustic pop at 96 BPM with female vocals, fingerpicked guitar, soft piano, and drums entering gradually in a wide final chorus.",
    "seed": 7,
    "max_new_tokens": 750,
    "response_format": "wav",
    "stream": false
  }' \
  --output minimax_music3.wav

python -c 'import wave; f=wave.open("minimax_music3.wav"); print({"channels": f.getnchannels(), "sample_rate": f.getframerate(), "sample_width_bytes": f.getsampwidth(), "duration_seconds": round(f.getnframes()/f.getframerate(), 2)})'
```

The file must be a non-empty WAV with `channels=2`, `sample_rate=32000`, and `sample_width_bytes=2`. `750` frames allow at most 30 seconds of audio. The duration can be shorter when the model emits its end-of-audio token.

## Capability boundaries

| Capability                                            | Model capability                           | Verified with this serving path                                                                                        |
| :---------------------------------------------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| Lyrics and music description to a complete song       | Supported                                  | Supported                                                                                                              |
| Output format                                         | 32 kHz, 16-bit stereo WAV                  | Supported                                                                                                              |
| Song duration                                         | Up to approximately five minutes           | The upstream reference set validates clips up to 30 seconds; a MiniMax long-form performance baseline is not published |
| Streaming generation                                  | Not supported                              | `stream` must be `false`                                                                                               |
| Voice selection or cloning                            | Not supported by this request contract     | `voice` and reference-audio fields are rejected                                                                        |
| Exact BPM, key, instrumentation, lyrics, or structure | Generative controls, not strict guarantees | Not guaranteed                                                                                                         |

SGLang-Omni documents byte-identical output for the same lyrics, instructions, seed, and length in the same setup. Do not assume byte-identical output across different model revisions, framework versions, or hardware stacks.

## Request contract

| Field             | Requirement                                                                                                                                  |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`           | Required, non-empty lyrics. Put `[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`, and other structure tags on their own lines.                   |
| `instructions`    | Required, non-empty description of genre, instruments, tempo, mood, vocals, arrangement, and production.                                     |
| `seed`            | Non-negative 64-bit integer. The default is `0`, which is deterministic rather than random.                                                  |
| `max_new_tokens`  | Acoustic-frame cap at 25 frames per second. The server maximum is `9,000`; use at most `7,500` for the model's documented five-minute scope. |
| `response_format` | Must be `wav`.                                                                                                                               |
| `stream`          | Must be `false`; the response is returned after model generation completes.                                                                  |

The tokenized text prompt is limited to 5,000 tokens. Shorten the lyrics or instructions if the server rejects an otherwise valid request at this limit.

<Warning>
  Put each structure tag on its own line. For example, use `[Verse]\nWalking down the street`. Lyrics placed on the same line as a tag can be removed during normalization without an error.
</Warning>

Do not send `temperature`, `top_p`, `top_k`, `repetition_penalty`, `voice`, reference-audio fields, `language`, or `task_type`. Tempo and vocal characteristics belong in `instructions`.

There is also an HTTP client concept called a **streaming response**, where a client writes an already-produced response body incrementally to disk. That does not make Music 3 model generation streaming. This guide uses ordinary `curl --output` to avoid conflating the two concepts.

## Weights, cache, and offline deployment

* Official weights: [`MiniMaxAI/MiniMax-Music3`](https://huggingface.co/MiniMaxAI/MiniMax-Music3)
* Pinned weights used here: [revision `fbdf52f`](https://huggingface.co/MiniMaxAI/MiniMax-Music3/tree/fbdf52fbaaca799592917417eb05f1899f1255ec)
* Default Hugging Face cache: `~/.cache/huggingface/hub`; set `HF_HOME` or `HF_HUB_CACHE` to relocate it.
* This guide uses `--local-dir`, so the server can load a stable filesystem path instead of resolving `main` at startup.
* No official MiniMax Music 3 ModelScope mirror is linked from the model card as of the documentation review date.

For an offline host, download the pinned revision on a connected machine, copy the complete directory to the target host, and start the service with the local path. Prevent accidental network resolution with:

```bash theme={null}
export HF_HUB_OFFLINE=1
export MUSIC3_MODEL_DIR=/data/models/MiniMax-Music3-fbdf52f

CUDA_VISIBLE_DEVICES=0 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000
```

If a download was interrupted or a file is corrupted, rerun the same pinned `hf download` command. Add `--force-download` only when you need to replace the local files rather than resume or reuse them.

## Production deployment and security

### Use two GPUs

SGLang-Omni places the autoregressive stage on the first visible GPU and the DiT/audio-decoder stage on the second:

```bash theme={null}
CUDA_VISIBLE_DEVICES=0,1 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000
```

This is a placement option, not a claim about minimum memory or performance on a particular two-GPU pair.

### Plan concurrency

Music 3 applies classifier-free guidance in both generation stages. Each request occupies two KV-cache rows in the autoregressive engine. If you raise the request limit, capacity-plan for twice the number of admitted requests:

```bash theme={null}
CUDA_VISIBLE_DEVICES=0,1 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000 \
  --max-running-requests 32
```

Do not increase this value before measuring peak memory and latency on your own hardware. Rendering a 10-second, 250-frame clip is the lowest-cost way to validate lyrics and instructions before a full song.

### Expose the service safely

Keep the model server on `127.0.0.1` when possible. If clients need remote access, place it behind an authenticated API gateway or reverse proxy with TLS, request-size limits, rate limits, timeouts, and network allowlists. Do not expose an unauthenticated `0.0.0.0:8000` endpoint to the internet. Treat lyrics and music descriptions as potentially sensitive data when configuring access logs and observability.

## Troubleshooting

| Symptom                                                                   | Likely cause                                                                            | Action                                                                                                                                                                                      |
| :------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `torch.cuda.is_available()` prints `False` or CUDA libraries fail to load | The driver, CUDA runtime, PyTorch, and SGLang-Omni packages are incompatible            | Use a fresh Python 3.10–3.12 environment, reinstall exactly `sglang-omni==0.1.3`, and verify the host driver supports its CUDA runtime before starting the server.                          |
| The process is killed or reports CUDA OOM                                 | The selected GPU cannot hold the colocated stages, or concurrency/KV cache is too large | Set `--max-running-requests 1`, test 250 frames, stop other GPU workloads, or use the two-GPU placement. Do not assume lowering `mem_fraction_static` will solve acoustic-stage memory use. |
| Weight download stalls, fails, or produces load errors                    | Insufficient disk, network interruption, or damaged local files                         | Confirm free disk, rerun the download at the pinned revision, and use `--force-download` only to replace corrupted files.                                                                   |
| `/health` returns `503` or connection fails                               | Model workers are still loading or a stage failed during startup                        | Wait for all stages to report ready, then inspect the server log for the first CUDA, dependency, weight, or inter-stage transport error.                                                    |
| The request returns HTTP `4xx`                                            | A required field is empty or an unsupported Speech API field was sent                   | Start from the minimal request above; keep `stream=false`, use WAV, and remove TTS sampling, voice, and reference-audio fields.                                                             |
| Lyrics are missing or the output is shorter than requested                | A structure tag shared a line with lyrics, or the model emitted the end token           | Put tags on separate lines. Remember that `max_new_tokens` is a cap, not a target.                                                                                                          |

For multi-GPU NCCL or UCX failures, first verify that the single-GPU command starts successfully, then check GPU visibility, peer connectivity, and the UCX prerequisites documented by SGLang-Omni.

## License and resources

| Resource                       | Link                                                                                                                                |
| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| Model repository               | [`MiniMaxAI/MiniMax-Music3`](https://huggingface.co/MiniMaxAI/MiniMax-Music3)                                                       |
| Inference code and prompt tool | [MiniMax-AI/MiniMax-Music3](https://github.com/MiniMax-AI/MiniMax-Music3)                                                           |
| Model license                  | [MiniMax-Music3 Community License](https://huggingface.co/MiniMaxAI/MiniMax-Music3/blob/main/LICENSE)                               |
| Serving reference              | [SGLang-Omni Music 3 Cookbook for `v0.1.3`](https://github.com/sgl-project/sglang-omni/blob/v0.1.3/docs/cookbook/minimax_music3.md) |

The model license includes attribution, commercial revenue thresholds, safeguard, intellectual-property, and Acceptable Use Policy requirements. Read the authoritative license and implement all applicable terms before offering Music 3 to third parties. SGLang-Omni is distributed separately under Apache-2.0.