Guide
MiniMax Music 1.5 Developer Guide: API Params, Pricing, and Integration
Capability boundaries, key request parameters, per-song pricing, and practical integration patterns
На этой странице
What MiniMax Music 1.5 Does and Where It Stops
MiniMax Music 1.5 is an audio generation model that turns text into music. It sits on the HiAPI.ai unified interface under the model family minimax-music-1.5, with a single visible route entity of the same name. If you are building a feature that needs a short, self-contained musical piece from a description plus words, this is the tool. If you need stem separation, real-time jamming, voice cloning, or long-form album sequencing, it is not.
The mental model is simple: two text inputs go in, one audio file comes out. The first input is a prompt that describes the musical style—genre, mood, instrumentation. The second is lyrics, the words to be sung, optionally annotated with structure tags. The model does not accept a reference audio file, does not do style transfer from an uploaded track, and does not return MIDI or notation. Its output is encoded audio only.
That boundary matters for architecture. Because the output is a finished audio artifact rather than a stream of notes, your integration is closer to an image-generation pipeline than to a synthesizer: you assemble a request, wait for a complete render, then store or serve the bytes. There is no partial-result streaming contract to design around, and no post-generation editing API. Plan for one request to produce one song.
In practical terms, treat MiniMax Music 1.5 as a renderer, not a co-writer. Your application owns the creative brief, the lyric authoring, the validation, the retry policy, and the storage. The model owns the acoustic realization. Keeping that division clean is the difference between a maintainable feature and a pile of prompt hacks.
The Two Required Inputs: prompt and lyrics
Every request needs both prompt and lyrics. Neither has a default, and omitting either fails validation. They serve different jobs, and conflating them is the most common source of disappointing output.
prompt: the compact style spec
prompt is a string between 10 and 300 characters. Its job is to state genre, mood, and instrumentation. Think of it as a sentence you would hand a session musician: "warm indie folk, fingerpicked acoustic guitar, brushed drums, hopeful and unhurried." Keep it dense and adjective-driven. Do not paste lyrics here, and do not describe structure—structure belongs on the other field.
Because the ceiling is 300 characters, you cannot be exhaustive. Prioritize the two or three attributes that most define the target sound. If your product lets users pick from style presets, compile each preset into a tight prompt template server-side so the client never has to guess at phrasing.
lyrics: the structured payload
lyrics is a string between 10 and 600 characters. It carries the words, one phrase per line, separated by \n. It also carries optional structure tags. The 600-character cap is the tighter constraint in practice—it is roughly a short verse and chorus, not a full song cycle. Budget your lyric generation accordingly.
Why the split matters
When the prompt contains lyric fragments, the model receives conflicting signals about what is style and what is content. Output quality degrades, and debugging becomes guesswork because you cannot tell which field caused a change. Keep prompt as reusable style configuration and lyrics as per-request content. That separation also makes caching and A/B testing tractable: swap one field, hold the other constant.
Validate both lengths client-side before you call the API. A rejected request still costs you a round trip and, if your retry logic is naive, a duplicate charge.
Structuring Lyrics with Line Breaks and Section Tags
The lyrics field is not free-form prose. It is a light markup format, and using it correctly gives you meaningful control over how the track is laid out.
One phrase per line
Separate each sung phrase with \n. Do not wrap long lines manually and do not use paragraph breaks—the line break is the phrase boundary. A dense block of text with no newlines tends to produce mushy phrasing and unpredictable pacing.
Section tags
The field supports five structure tags: [intro], [verse], [chorus], [bridge], and [outro]. Place a tag on its own line before the lines it governs. A minimal well-formed lyric looks like this:
[intro]
Amber light on the kitchen floor
[verse]
We stacked the years in a coffee tin
Counted the reasons to begin
[chorus]
Hold the door, the morning's coming through
[outro]
And the room stays warm
Three habits pay off. First, always open with [intro] and close with [outro] if you want a sense of arrival and departure—without them the render can start and stop abruptly. Second, keep sections short; the 600-character ceiling leaves no room for a double chorus with a repeated refrain written out in full. Third, use [bridge] sparingly and only when you actually want a contrast section, since each tag consumes characters that could hold words.
Generating lyrics programmatically
If an LLM writes your lyrics, constrain its output to this format in the prompt: newline-separated phrases, tags from the fixed set, total length under the cap. Then validate structurally—count lines, check that every bracket token is in the allowed set, and reject before dispatch. This catches the common failure where a model emits [pre-chorus] or a markdown heading instead of a supported tag.
Controlling Output: audio_format, bitrate, and sample_rate
Three optional parameters govern what bytes come back. All three have sensible defaults, so a minimal request works out of the box—but for production pipelines you should set them explicitly rather than inherit them by accident.
audio_format
String enum: mp3, wav, pcm. Default mp3.
mp3 is the right default for anything a user will play back directly—web players, mobile apps, email attachments. It is compact and universally decodable. wav gives you uncompressed audio suitable for downstream processing, editing, or re-encoding at higher quality. pcm returns raw samples and is the correct choice when your pipeline feeds a DSP stage, a mixer, or a speech-to-text or analysis step that expects headerless audio.
bitrate
Integer enum, in bits per second: 32000, 64000, 128000, 256000. Default 256000.
Bitrate is a quality-versus-size dial. Use 256000 for a final deliverable where fidelity matters. 128000 is a reasonable general-purpose middle ground for streaming or storage-constrained contexts. 64000 and 32000 are for previews, thumbnails of audio, or bandwidth-constrained delivery—expect audible degradation on dense instrumentation. Note that bitrate is meaningful for compressed formats; if you request wav or pcm, the format's encoding behavior dominates and bitrate should not be treated as your primary size lever.
sample_rate
Integer enum, in Hz: 16000, 24000, 32000, 44100. Default 44100.
44100 is the standard music rate and the safe default for anything a listener hears. Drop to 32000 or 24000 only if your downstream consumer is speech-oriented or you are deliberately conserving space. 16000 is telephony-grade and will sound thin for music—reserve it for analysis pipelines that resample anyway.
Picking a combination
For user-facing playback, the default triple (mp3, 256000, 44100) is correct and you should not change it. For editing and post-production, choose wav at 44100 and ignore bitrate. For analysis, pcm at a rate your analyzer expects. For previews, mp3 at 128000 or 64000. Encode these as named presets in your own codebase rather than scattering magic strings through call sites.
Pricing and Cost Modeling at $0.07 per Song
HiAPI.ai bills MiniMax Music 1.5 per song. There is a single tier: $0.07 per song, with the billing unit recorded as per_song. There are no token counts, no per-second metering, and no duration tiers to reason about. Every successful generation that yields a song is one billable unit.
That simplicity is genuinely useful for cost modeling. Token-based pricing forces you to estimate input and output lengths and multiply; per-second pricing forces you to predict duration before you have any. Per-song pricing collapses all of that into counting.
From unit price to product economics
The arithmetic is one multiplication. If a user generates n songs, their cost is n times the unit price. From there you can derive the numbers that actually drive product decisions: average songs per session, cost per active user per month, and the generation volume at which a higher-tier plan makes sense. Because the meter is discrete, these estimates stay accurate as long as your volume forecast is accurate—there is no variance from prompt length or output encoding.
A few modeling consequences worth internalizing:
- Format choices do not change the bill. Requesting
wavat44100costs the same asmp3at256000. Choose encoding for engineering reasons, never to save money. - Prompt and lyric length do not change the bill. Validate lengths for correctness and user experience, not for cost.
- Retries do. A failed-then-retried request is a second unit. Aggressive automatic retries on transient errors are a real cost line, which is why client-side validation and a disciplined retry policy are financial controls, not just hygiene.
- Regenerations are the dominant variable. A "try again" button is the main driver of volume. Design its UX deliberately—offer variations within a session, but make regeneration an explicit action with visible context.
For current live figures, consult the pricing panel on the site; treat the numbers in your own dashboards as derived from it, not hardcoded independently.
A Practical Integration Flow
The call sequence is short and fits comfortably inside a single request handler. The discipline lives in what happens before and after the network call.
Step 1: Validate on the client
Check prompt length (10–300), lyrics length (10–600), and that every bracket token in the lyrics belongs to the allowed tag set. Reject locally with a helpful message. This is the cheapest possible gate and it prevents a meaningful fraction of avoidable requests.
Step 2: Build the request
Assemble the payload with both required fields and any explicit output settings. Resolve format, bitrate, and sample rate from a named preset rather than inline literals. If your product uses style presets, map the chosen preset to a prompt template here, keeping the lyrics field purely user- or LLM-authored content.
{
"prompt": "warm indie folk, fingerpicked acoustic guitar, brushed drums",
"lyrics": "[verse]\nWe stacked the years in a coffee tin\n[chorus]\nHold the door, the morning's coming through",
"audio_format": "mp3",
"bitrate": 256000,
"sample_rate": 44100
}
Step 3: Dispatch and handle the response
Treat the returned audio as an opaque artifact. Do not attempt to parse it in the request handler. Write it to your object store under a content-addressed or UUID key, record the request parameters and the resulting object key in your database, and return a stable reference to your own client rather than proxying raw bytes through your API tier. This decouples generation latency from playback and gives you a natural place to attach metadata for regeneration.
Step 4: Deliver
Serve from your storage layer with appropriate caching headers. If files are large, stream them; if they are small and repeatedly requested, cache at the edge. Because format is fixed at generation time, you may need to transcode server-side for clients that cannot decode your chosen format—decide this before you pick your preset, not after.
Step 5: Make regeneration a first-class flow
Store the original request alongside the artifact. A "regenerate" action then becomes a re-dispatch of a known-good payload rather than a reconstruction from UI state, which eliminates a whole class of "the second attempt sounded different and we don't know why" bugs. The model page for MiniMax Music 1.5 documents the same parameters if you need to confirm field names while wiring this up.
Failure Modes and Validation Checklist
Most integration failures are predictable and cheap to prevent. Run this checklist before every dispatch.
Pre-flight gates
- Prompt present and in range. Non-empty, 10–300 characters. Trim whitespace before counting; a prompt of nine characters plus trailing spaces will still fail.
- Lyrics present and in range. Non-empty, 10–600 characters, counted after trimming.
- Structure tags are legal. Every bracketed token is one of
[intro],[verse],[chorus],[bridge],[outro]. Reject invented tags rather than stripping them silently—silent mutation makes output regressions untraceable. - Line breaks are real newlines. If your lyrics arrive as JSON from a client, confirm that
\nsequences survived serialization and were not collapsed into spaces. This is the single most common cause of dense, unstructured output. - Enums are exact.
audio_formatinmp3/wav/pcm;bitratein32000/64000/128000/256000(as an integer);sample_ratein16000/24000/32000/44100. Typos likeMP3or44.1kbelong in your translation layer, not in the request.
Retry discipline
Distinguish error classes. Validation errors will never succeed on retry—fix the payload or surface the message to the user. Transient failures deserve a bounded retry with backoff, capped at two or three attempts; each attempt is a billable unit. Generation timeouts need a different treatment again: log the request, fail gracefully, and let the user choose whether to try again, because the failed call may still consume a unit.
Common output complaints and their real causes
If the render sounds generic, the prompt is probably under-specified on instrumentation—add concrete instruments, not more adjectives. If phrasing feels flat, check that lyrics use one phrase per line with newlines intact. If the track starts or stops abruptly, add [intro] and [outro]. If the piece is shorter than expected, remember the 600-character lyric ceiling and confirm your generator is not silently truncating.
Wire these checks into a single validation function that runs in both your client and your server handler. One implementation, two call sites, no drift—and a much smaller share of your generation budget spent on requests that were never going to succeed.
Похожие статьи
Все статьи →-
Guide
gpt-6.2-sol Getting Started Guide: Capability Boundaries, API Integration, and Token Pricing Essentials
Integration decisions and practical essentials for engineering teams
-
Guide
gpt-6.2-astra Getting Started Guide: Text Model Capability Boundaries, Integration Essentials, and Cost Control
-
Guide
Tripo H3.1 Getting Started Guide: Choosing Among Three Input Modes, Parameters, and Pricing
A practical guide for developers on 3D generation integration decisions and cost control