{
"openapi": "3.1.0",
"info": {
"title": "MiniMax Music Generation API",
"description": "MiniMax music generation API with support for creating music from text prompts and lyrics",
"license": {
"name": "MIT"
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.minimax.io"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v1/music_generation": {
"post": {
"summary": "Music Generation",
"operationId": "generateMusic",
"tags": [ "Music" ],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": true,
"description": "The media type of the request body. Must be set to `application/json` to ensure the data is sent in JSON format.",
"schema": {
"type": "string",
"enum": [ "application/json" ],
"default": "application/json"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateMusicReq"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateMusicResp"
}
}
}
}
}
}
},
"/v1/music_cover_preprocess": {
"post": {
"summary": "Music Cover Preprocess",
"operationId": "coverPreprocess",
"tags": [ "Music" ],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": true,
"description": "The media type of the request body. Must be set to `application/json` to ensure the data is sent in JSON format.",
"schema": {
"type": "string",
"enum": [ "application/json" ],
"default": "application/json"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoverPreprocessReq"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoverPreprocessResp"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Error": {
"type": "object",
"required": [ "error", "message" ],
"properties": {
"error": {
"type": "integer",
"format": "int32",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"GenerateMusicReq": {
"type": "object",
"required": [ "model" ],
"properties": {
"model": {
"type": "string",
"description": "The model name. Options:\n\n- `music-3.0` (recommended): Text-to-music generation. Available to Token Plan and paid users only, with an RPM of 120.\n- `music-2.6`: Previous-generation text-to-music model. Available to Token Plan and paid users only, with an RPM of 120.\n- `music-cover`: Cover generation from a reference audio. Available to Token Plan and paid users only, with an RPM of 120.\n- `music-3.0-free`: Free-tier version of `music-3.0`. Available to all users via API Key, with an RPM of 3.\n- `music-2.6-free`: Free-tier version of `music-2.6`. Available to all users via API Key, with an RPM of 3.\n- `music-cover-free`: Free-tier version of `music-cover`. Available to all users via API Key, with an RPM of 3.",
"enum": [ "music-3.0", "music-2.6", "music-cover", "music-3.0-free", "music-2.6-free", "music-cover-free" ]
},
"prompt": {
"type": "string",
"description": "A description of the music, specifying style, mood, and scenario.\n\nFor example: \"`Pop, melancholic, perfect for a rainy night`\".\n
\nNote:\n- For `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free` with `is_instrumental: true`: Required. Length: 1–2000 characters.\n- For `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free` (non-instrumental): Optional. Length: 0–2000 characters.\n- For `music-cover` / `music-cover-free`: Required. Describes the target cover style. Length: 10–300 characters.",
"maxLength": 2000
},
"lyrics": {
"type": "string",
"description": "Song lyrics, using `\\n` to separate lines. Supports structure tags: `[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`.\n
\nNote:\n- For `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free` with `is_instrumental: true`: Not required.\n- For `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free` (non-instrumental): Required. Length: 1–3500 characters.\n- For `music-cover` / `music-cover-free`: Optional. If omitted, lyrics are automatically extracted from the reference audio via ASR. Length: 10–1000 characters.\n- When `lyrics_optimizer: true` and `lyrics` is empty, the system will auto-generate lyrics from `prompt`.",
"minLength": 1,
"maxLength": 3500
},
"stream": {
"type": "boolean",
"description": "Whether to use streaming output.",
"default": false
},
"output_format": {
"type": "string",
"description": "The output format of the audio. Options: `url` or `hex`.\n\nWhen `stream` is `true`, only `hex` is supported.\n\n⚠️ Note: `url` links expire after 24 hours, so download promptly.",
"enum": [ "url", "hex" ],
"default": "hex"
},
"audio_setting": {
"$ref": "#/components/schemas/AudioSetting"
},
"lyrics_optimizer": {
"type": "boolean",
"description": "Whether to automatically generate lyrics based on the `prompt` description. Only supported on `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free`.\n\nWhen set to `true` and `lyrics` is empty, the system will automatically generate lyrics from the prompt. Default: `false`.",
"default": false
},
"is_instrumental": {
"type": "boolean",
"description": "Whether to generate instrumental music (no vocals). Only supported on `music-3.0` / `music-3.0-free` / `music-2.6` / `music-2.6-free`.\n\nWhen set to `true`, the `lyrics` field is not required. Default: `false`.",
"default": false
},
"audio_url": {
"type": "string",
"description": "URL of the reference audio. Only used with `music-cover` / `music-cover-free` model. Exactly one of `audio_url` or `audio_base64` must be provided. Mutually exclusive with `cover_feature_id`.\n\nReference audio constraints:\n- Duration: 6 seconds to 6 minutes\n- Size: max 50 MB\n- Format: common audio formats (mp3, wav, flac, etc.)"
},
"audio_base64": {
"type": "string",
"description": "Base64-encoded reference audio. Only used with `music-cover` / `music-cover-free` model. Exactly one of `audio_url` or `audio_base64` must be provided. Mutually exclusive with `cover_feature_id`.\n\nReference audio constraints:\n- Duration: 6 seconds to 6 minutes\n- Size: max 50 MB\n- Format: common audio formats (mp3, wav, flac, etc.)"
},
"cover_feature_id": {
"type": "string",
"description": "Feature ID returned by the [Music Cover Preprocess](/api-reference/music-cover-preprocess) API. Used in the **two-step cover workflow** to generate a cover with modified lyrics.\n\nOnly used with `music-cover` / `music-cover-free` model. Mutually exclusive with `audio_url` and `audio_base64`.\n\n- When provided, `lyrics` is required (length: 10–1000 characters)\n- The `cover_feature_id` is valid for 24 hours\n- Same audio content returns the same `cover_feature_id`"
}
},
"example": {
"model": "music-3.0",
"prompt": "Indie folk, melancholic, introspective, longing, solitary walk, coffee shop",
"lyrics": "[verse]\nStreetlights flicker, the night breeze sighs\nShadows stretch as I walk alone\nAn old coat wraps my silent sorrow\nWandering, longing, where should I go\n[chorus]\nPushing the wooden door, the aroma spreads\nIn a familiar corner, a stranger gazes",
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
}
}
},
"GenerateMusicResp": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/MusicData"
},
"base_resp": {
"$ref": "#/components/schemas/BaseResp"
}
},
"example": {
"data": {
"audio": "hex-encoded audio data",
"status": 2
},
"trace_id": "04ede0ab069fb1ba8be5156a24b1e081",
"extra_info": {
"music_duration": 25364,
"music_sample_rate": 44100,
"music_channel": 2,
"bitrate": 256000,
"music_size": 813651
},
"analysis_info": null,
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
},
"AudioSetting": {
"type": "object",
"description": "Audio output configuration",
"properties": {
"sample_rate": {
"type": "integer",
"description": "Sampling rate. Options: `16000`, `24000`, `32000`, `44100`."
},
"bitrate": {
"type": "integer",
"description": "Bitrate. Options: `32000`, `64000`, `128000`, `256000`."
},
"format": {
"type": "string",
"description": "Audio format. Options: `mp3`, `wav`, `pcm`.",
"enum": [ "mp3", "wav", "pcm" ]
}
}
},
"MusicData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Music generation status:\n\n1: In progress\n\n2: Completed"
},
"audio": {
"type": "string",
"description": "Returned when `output_format` is `hex`.\n\nContains the audio file as a hexadecimal-encoded string."
}
}
},
"BaseResp": {
"type": "object",
"description": "Status code and details",
"properties": {
"status_code": {
"type": "integer",
"description": "Status codes and their meanings:\n\n`0`: Success\n\n`1002`: Rate limit triggered, retry later\n\n`1004`: Authentication failed, check API Key\n\n`1008`: Insufficient balance\n\n`1026`: Content flagged for sensitive material\n\n`2013`: Invalid parameters, check input\n\n`2049`: Invalid API Key\n\nFor more information, please refer to the [Error Code Reference](/api-reference/errorcode)."
},
"status_msg": {
"type": "string",
"description": "Detailed error message"
}
}
},
"CoverPreprocessReq": {
"type": "object",
"required": [ "model" ],
"properties": {
"model": {
"type": "string",
"description": "Model name. Must be `music-cover`.",
"enum": [ "music-cover" ]
},
"audio_url": {
"type": "string",
"description": "URL of the reference audio. Exactly one of `audio_url` or `audio_base64` must be provided.\n\nReference audio constraints:\n- Duration: 6 seconds to 6 minutes\n- Size: max 50 MB\n- Format: common audio formats (mp3, wav, flac, etc.)"
},
"audio_base64": {
"type": "string",
"description": "Base64-encoded reference audio. Exactly one of `audio_url` or `audio_base64` must be provided.\n\nReference audio constraints:\n- Duration: 6 seconds to 6 minutes\n- Size: max 50 MB\n- Format: common audio formats (mp3, wav, flac, etc.)"
}
},
"example": {
"model": "music-cover",
"audio_url": "https://example.com/song.mp3"
}
},
"CoverPreprocessResp": {
"type": "object",
"properties": {
"cover_feature_id": {
"type": "string",
"description": "Unique identifier for the preprocessed audio features. Valid for 24 hours. Pass this to the [Music Generation API](/api-reference/music-generation) `cover_feature_id` parameter for two-step cover generation.\n\nSame audio content returns the same `cover_feature_id` (MD5-based deduplication)."
},
"formatted_lyrics": {
"type": "string",
"description": "Structured lyrics extracted from the reference audio via ASR, formatted with section tags such as `[Verse]`, `[Chorus]`, `[Bridge]`, etc. You can modify these lyrics before passing them to the Music Generation API."
},
"structure_result": {
"type": "string",
"description": "JSON string containing the song structure analysis result, including segment types (`intro`, `verse`, `chorus`, `bridge`, `outro`, `inst`, `silence`) and their start/end timestamps in seconds."
},
"audio_duration": {
"type": "number",
"format": "double",
"description": "Duration of the reference audio in seconds."
},
"trace_id": {
"type": "string",
"description": "Unique trace ID for request tracking."
},
"base_resp": {
"$ref": "#/components/schemas/BaseResp"
}
},
"example": {
"cover_feature_id": "a1b2c3d4e5f67890abcdef1234567890",
"formatted_lyrics": "[Verse 1]\nFirst line of the song\nSecond line continues\n\n[Chorus]\nThis is the chorus\nSinging out loud",
"structure_result": "{\"num_segments\":4,\"segments\":[{\"start\":0,\"end\":15.5,\"label\":\"intro\"},{\"start\":15.5,\"end\":45.2,\"label\":\"verse\"},{\"start\":45.2,\"end\":75.0,\"label\":\"chorus\"},{\"start\":75.0,\"end\":90.0,\"label\":\"outro\"}]}",
"audio_duration": 90.0,
"trace_id": "061e5f144eb7f10b1fdde81126e24f91",
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "`HTTP: Bearer Auth`\n- Security Scheme Type: http\n- HTTP Authorization Scheme: `Bearer API_key`, can be found in [Account Management>API Keys](https://platform.minimax.io/user-center/basic-information/interface-key)."
}
}
}
}