> ## Documentation Index > Fetch the complete documentation index at: https://docs.mage.space/llms.txt > Use this file to discover all available pages before exploring further. # MiniMax Music 3 > Generate audio with MiniMax Music 3 through the Mage API: the fields of POST /v1/minimax_music/generate, its options by model, the rules it enforces, and its gem price. MiniMax's open-weights song model: complete songs with sung vocals that follow your lyrics, or instrumentals, up to 5 minutes, as a 44.1 kHz stereo MP3, with LoRAs. Put the words in `lyrics` and the sound in the prompt. | Detail | | | - | - | | Type | Audio | | Models | `minimax-music-3` (MiniMax Music 3, default) | | Image inputs | None | | Video inputs | None | | Gems | 125 at the default settings | | Model page | [MiniMax Music 3](https://docs.mage.space/models/minimax-music-3.md) | ## Mentions This model takes no `@handle` mentions: saved characters, references, and audio references are not available on it. See [Characters and references](https://docs.mage.space/api/inputs.md#characters-and-references). ## Rules A request that breaks one of these is refused with `400 invalid_config` before any gems are charged. * The prompt describes the music, at most 4000 characters: genre, tempo and key, mood and how it builds, the vocalist (name the voice, or the song may come out instrumental), and the instruments. * `lyrics` holds the words to sing, at most 6000 characters. Put each section tag (\[intro], \[verse], \[pre-chorus], \[chorus], \[bridge], \[outro]) on its own line: words on a tag's line are dropped. * Leave `lyrics` empty, or set `instrumental` to true, for an instrumental. * `duration` is the longest the song may run, and the price; the model ends the song when its lyrics and arrangement are done, often sooner. Every field below that you leave out keeps its default. Option values are the tokens listed per field; a numeric token may be sent as a number. Fields the schema does not list pass through to the model unchanged. The exact charge for other settings is in the response's `billing.gems_charged`, and the balance at [`GET /v1/account`](https://docs.mage.space/api/endpoints/get-account). ## OpenAPI ````yaml api/openapi.json POST /v1/minimax_music/generate openapi: 3.1.0 info: title: Mage API version: v1 description: >- Run Mage models from your own code: submit a generation, poll its status, download the result. Every request is paid in gems. contact: name: Mage url: https://www.mage.space email: mage@mage.space servers: - url: https://api.mage.space description: Production security: - apiKey: [] tags: - name: Requests description: Submit, poll, and cancel generations. - name: Catalog description: What the API can generate with. - name: Account description: The gems balance. - name: Uploads description: Large input files. - name: Characters description: Saved characters a prompt mentions by `@handle`. - name: References description: Saved image and audio references a prompt mentions by `@handle`. - name: Image models description: One endpoint per image architecture. - name: Video models description: One endpoint per video architecture. - name: Audio models description: One endpoint per audio architecture. paths: /v1/minimax_music/generate: post: tags: - Audio models summary: MiniMax Music 3 description: Generate audio with MiniMax Music 3. operationId: generate_minimax_music parameters: - name: Idempotency-Key in: header required: false description: >- A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key. schema: type: string minLength: 1 maxLength: 255 requestBody: required: true description: A partial config for MiniMax Music 3. content: application/json: schema: type: object properties: prompt: type: string minLength: 1 description: The text prompt. seed: description: >- Integer seed for reproducible output; omit or send null for a random seed. anyOf: - type: integer - type: 'null' model_id: type: string enum: - minimax-music-3 description: The model variant to generate with. default: minimax-music-3 duration: type: string enum: - '30' - '60' - '120' - '180' - '240' - '300' description: Clip length in seconds, as a token. default: '120' lyrics: type: string default: '' instrumental: type: boolean default: false required: - prompt additionalProperties: true example: prompt: >- Acoustic pop, 96 BPM, C major, warm and intimate, building into the chorus. Soft female lead, close and breathy, light harmonies in the chorus. Fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus. duration: '120' lyrics: |- [verse] Morning light filtering through the pine Every quiet street is yours and mine [chorus] Softly the world begins to breathe responses: '202': description: >- The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing. content: application/json: schema: $ref: '#/components/schemas/Request' example: request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff status: in_progress architecture: minimax_music model_id: minimax-music-3 created_at: '2026-09-17T14:52:48.000Z' updated_at: '2026-09-17T14:52:49.000Z' billing: mode: gems gems_charged: 125 result: null error: null status_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status cancel_url: >- https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel '400': $ref: '#/components/responses/InvalidGenerateRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientGems' '403': $ref: '#/components/responses/GenerationForbidden' '410': $ref: '#/components/responses/ArchitectureRetired' '429': $ref: '#/components/responses/TooManyRequests' '451': $ref: '#/components/responses/ExternalContentBlock' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: typescript label: TypeScript SDK source: |- import Mage from '@mage-space/sdk'; const mage = new Mage(); // reads MAGE_API_KEY const request = await mage.run('minimax_music', { prompt: 'Acoustic pop, 96 BPM, C major, warm and intimate, building into the chorus. Soft female lead, close and breathy, light harmonies in the chorus. Fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus.', duration: '120', lyrics: '[verse]\nMorning light filtering through the pine\nEvery quiet street is yours and mine\n[chorus]\nSoftly the world begins to breathe', }); console.log(request.result.url); - lang: python label: Python SDK source: |- from mage_space import Mage mage = Mage() # reads MAGE_API_KEY request = mage.run("minimax_music", { "prompt": "Acoustic pop, 96 BPM, C major, warm and intimate, building into the chorus. Soft female lead, close and breathy, light harmonies in the chorus. Fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus.", "duration": "120", "lyrics": "[verse]\nMorning light filtering through the pine\nEvery quiet street is yours and mine\n[chorus]\nSoftly the world begins to breathe", }) print(request["result"]["url"]) components: schemas: Request: type: object properties: request_id: type: string format: uuid description: The request id, also the id in `status_url` and `cancel_url`. status: type: string enum: - queued - in_progress - completed - failed - cancelled description: >- `queued` and `in_progress` are live; `completed`, `failed`, and `cancelled` are final. architecture: type: string description: The architecture the request generates with. model_id: anyOf: - type: string - type: 'null' description: The model variant, when the architecture has variants. created_at: type: string format: date-time description: When the request was accepted. updated_at: type: string format: date-time description: When the request last changed. billing: type: object properties: mode: type: string const: gems description: Every API request is paid in gems. gems_charged: type: number description: Gems debited for the request. gems_refunded: description: Gems returned to the account; present on failed requests. type: number required: - mode - gems_charged additionalProperties: false result: anyOf: - type: object properties: type: type: string enum: - image - video - audio description: The media type of the output. url: type: string format: uri description: Where to download the output. width: type: integer description: Output width in pixels; 0 for audio. height: type: integer description: Output height in pixels; 0 for audio. seed: type: integer description: The seed the generation ran with. expires_at: anyOf: - type: string format: date-time - type: 'null' description: >- When `url` stops working: 30 days after the request for temporary media, or null for permanent media. moderation: type: object properties: nsfw: type: boolean description: Whether moderation flagged the output as NSFW. required: - nsfw additionalProperties: false description: Moderation flags on the output. required: - type - url - width - height - seed - expires_at - moderation additionalProperties: false - type: 'null' description: The output once `status` is `completed`, else null. error: anyOf: - type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - character_not_found - reference_not_found - not_found - insufficient_gems - payment_required - forbidden - content_blocked - request_finished - handle_taken - too_many_requests - generation_failed - preprocess_refused - internal_error description: A stable error code. message: type: string description: What went wrong, for a person. reason: description: >- Present on `content_blocked` when the model's external provider refused the content, not Mage: `likeness` (a real person or celebrity), `ip` (copyrighted or trademarked material), `nsfw` (content past the model's own limit: sexual, violent, or otherwise sensitive), `minors` (may involve a minor), `audio` (the audio, usually copyrighted music or a real voice), or `unspecified` (the provider gave no reason). An open set: treat an unknown value as `unspecified`. type: string enum: - likeness - ip - nsfw - minors - audio - unspecified stage: description: >- With `reason`: `input` when the provider refused the prompt or input media, `output` when it refused the generated media, or null when it did not say. anyOf: - type: string enum: - input - output - type: 'null' required: - code - message additionalProperties: false - type: 'null' description: Why the request failed once `status` is `failed`, else null. status_url: type: string format: uri description: Poll this URL for the request. cancel_url: type: string format: uri description: POST to this URL to stop the request. required: - request_id - status - architecture - model_id - created_at - updated_at - billing - result - error - status_url - cancel_url additionalProperties: false Error: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - character_not_found - reference_not_found - not_found - insufficient_gems - payment_required - forbidden - content_blocked - request_finished - handle_taken - too_many_requests - generation_failed - preprocess_refused - internal_error description: A stable error code; treat an unknown code by its HTTP status. message: type: string description: What went wrong, for a person. request_id: description: >- The request the refusal belongs to, when one was recorded before the refusal. type: string format: uuid gems_required: description: The price of the refused generation, on `insufficient_gems`. type: number docs_url: description: Where to read the API reference, on `not_found`. type: string format: uri handle: description: The handle that is taken, on `handle_taken`. type: string required: - code - message additionalProperties: true description: Further fields depend on the code. required: - error additionalProperties: false responses: InvalidGenerateRequest: description: >- The body is not a JSON object, sets a server-owned field, contradicts the architecture, breaks a field's type or token list, mentions an `@handle` that does not resolve or that the model does not support, exceeds the image or audio budget, or breaks a model rule; or the `Idempotency-Key` is malformed. `invalid_config` names the field, the handle, or the rule. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_config message: '`resolution` must be one of: 768P, 2K.' Unauthorized: description: The key is missing, malformed, unknown, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: The API key is invalid or has been revoked. InsufficientGems: description: >- The gems balance is below the price (`insufficient_gems`; `gems_required` is the price), or the account has never paid (`payment_required`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_gems message: >- This generation costs 40 gems and the account balance is too low. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff gems_required: 40 GenerationForbidden: description: >- The account cannot generate (`forbidden`), or the request was blocked by the content policy before it ran (`content_blocked`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: content_blocked message: The request was blocked by Mage's content policy. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff ArchitectureRetired: description: The architecture has been retired. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: architecture_retired message: This architecture has been retired. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff TooManyRequests: description: >- The account already has its cap of generations in flight (20 unless set otherwise for the account), web and API together. Wait for some to finish. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: too_many_requests message: >- At most 20 generations may be in flight at once for this account; 20 are running now. ExternalContentBlock: description: The request was blocked by an external content restriction. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: content_blocked message: The request was blocked by an external content restriction. request_id: d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff InternalError: description: >- Something failed on Mage's side. Retry, and contact support if it persists. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: >- Something went wrong on our side. Retry, and contact support if it persists. securitySchemes: apiKey: type: http scheme: bearer description: >- Create a key in [API → API Keys](https://www.mage.space/api?tab=api-keys): select **Create API key**, name it in the popup, then select **Create key**. Copy the one-time key and send it as `Authorization: Bearer mage_sk_…`. Keys are for server-side code only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.