MiniMax Speech — Cloud Text-to-Speech, Voice Cloning & Voice Design

This skill covers the CLOUD platform API only (api.minimax.io, Bearer auth with a platform API key). It does not cover the local Electron gateway — see minimax-local-audio for that, and do not mix their parameter shapes: this API uses real JSON types ("speed": 0.9), the local gateway uses strings ("speed": "1").

Quick start

curl -s -X POST "https://api.minimax.io/v1/t2a_v2" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "The text to speak.",
    "output_format": "url",
    "language_boost": "English",
    "voice_setting": {"voice_id": "English_CaptivatingStoryteller", "speed": 0.9, "vol": 1, "pitch": 0, "emotion": "calm"},
    "audio_setting": {"sample_rate": 44100, "bitrate": 256000, "format": "wav", "channel": 1}
  }' | jq -r '.data.audio' | xargs curl -sL -o narration.wav

No GroupId parameter is needed. The call is synchronous — audio comes back in one response.

Phase 0: Choose the approach

For voiceover against picture, always use the sync endpoint and render each line as its own call. See Phase 4 — this is the single most important technique in this skill.

Phase 1: Pick the model

emotion: "whisper" is not available on speech-2.8 models. Interjection tags are speech-2.8 only.

Phase 2: Pick a voice

332 preset voices across 40+ languages. Full list in references/voice-catalog.md.

English narration shortlist — the names are the only descriptor the platform publishes, so audition 2–3 before committing to a long script:

To list every voice available on the account (system + cloned + designed):

curl -s -X POST "https://api.minimax.io/v1/get_voice" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{"voice_type": "all"}' | jq

Phase 3: Shape the delivery

voice_setting

audio_setting

For anything that will be mixed or edited, request wav at 44100. Start lossless; the edit will re-encode anyway.

language_boost

Set it explicitly ("English", "French", …, or "auto"). 40+ values — see the reference. It measurably improves pronunciation of proper nouns.

Other controls

• pronunciation_dict — force pronunciations: {"tone": ["Omg/Oh my god", "moments-hq/moments H Q"]}. Essential for brand names, URLs and acronyms.
• voice_modify — pitch, intensity, timbre each [-100, 100], plus sound_effects ∈ spacious_echo, auditorium_echo, lofi_telephone, robotic.
• timbre_weights — blend up to 4 voices, weights [1, 100]. Legacy.

Phase 4: Timing — pauses and timestamps

This is what makes MiniMax genuinely good for narration against picture.

Inline pauses — <#x#>

Insert silence of x seconds directly in the text:

"One code.<#0.45#>No app.<#0.45#>No sign-up."

• Range [0.01, 99.99], up to 2 decimal places.
• Must sit between speakable segments. Not at the very start or end, and never two in a row (<#1#><#1#> is invalid).
• ✅ Verified working on the sync endpoint.
• ⚠️ On the async endpoint, <#x#> is documented only for text_file_id (txt input), not for the inline text parameter. If a pause comes back spoken literally, that asymmetry is why.

There is no SSML. <#x#> plus interjection tags are the entire inline control surface.

Interjection tags — speech-2.8 models only

(laughs) (breath) (sighs) (inhale) (exhale) (clear-throat) (coughs) (chuckle) (groans) (pant) (gasps) (sniffs) (snorts) (burps) (lip-smacking) (humming) (hissing) (emm) (whistles) (sneezes) (crying) (applause)

A (breath) before an emotional line is the cheapest way to make a read sound human.

Timestamps — subtitle_enable

"subtitle_enable": true,
"subtitle_type": "word"

subtitle_type ∈ sentence (default) · word · word_streaming.

Returns data.subtitle_file — a URL to a JSON array. ✅ Verified live schema:

[
  {
    "text": "One code.",
    "pronounce_text": "One code.",
    "time_begin": 0.0,
    "time_end": 1037.78,
    "text_begin": 0, "text_end": 9,
    "is_final_segment": true,
    "timestamped_words": [
      { "word": "One", "time_begin": 47.41, "time_end": 189.63,
        "word_begin": 0, "word_end": 3 }
    ]
  }
]

All times are milliseconds. This gives word-accurate positions for cutting picture to narration, animating captions, or syncing subtitles.

The technique for voiceover against picture

Render each line as its own request, with identical voice_id, speed, pitch and emotion across all of them, then place the clips on a timeline yourself:

1. Every line's exact length arrives as extra_info.audio_length (ms).
2. Silence between lines is placed by you, frame-accurately — not guessed by the model.
3. One bad line can be re-rendered without disturbing the others.

Do not slow an entire read with speed: 0.7 to fill a duration — that stretches delivery and sounds artificial. Keep speed natural and buy time with placed silence.

# Place lines at exact timestamps
ffmpeg -i l1.wav -i l2.wav -i l3.wav -filter_complex \
 "[0]adelay=0|0[a];[1]adelay=9000|9000[b];[2]adelay=15000|15000[c];[a][b][c]amix=inputs=3:normalize=0" vo.wav

Phase 5: Voice cloning

Three steps. Requires account verification — status 2038 means the account is not cleared for cloning.

# 1. Upload the reference audio: mp3/m4a/wav, 10s–5min, ≤ 20 MB
curl -s -X POST "https://api.minimax.io/v1/files/upload" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -F "purpose=voice_clone" -F "file=@sample.wav"
# -> .file.file_id

# 2. Clone
curl -s -X POST "https://api.minimax.io/v1/voice_clone" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{"file_id": 123456, "voice_id": "MomentsNarrator01",
       "need_noise_reduction": true, "need_volume_normalization": true}'

# 3. Use it — pass voice_id straight into t2a_v2

voice_id naming rules: 8–256 chars · must start with a letter · letters, digits, -, _ only · must not end with - or _ · must be unique on the account.

⚠️ A cloned voice is deleted if unused for 7 days. Generate at least one line with it inside that window, or re-clone.

Phase 6: Voice design — describe a voice in words

The fastest way to a specific timbre with no sample to source. Costs $30 per 1M characters of preview text.

curl -s -X POST "https://api.minimax.io/v1/voice_design" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm, low, unhurried male narrator in his forties. Intimate and confiding, like a close friend telling a story late at night. Slight gravel, no announcer polish.",
    "preview_text": "Two hundred people came to your wedding. Two hundred phones."
  }'

Returns voice_id (shape ttv-voice-<timestamp>-<hex>) and trial_audio (hex-encoded). preview_text max 500 chars. Pass an explicit voice_id to name it yourself. Then use that voice_id in t2a_v2 exactly like a preset.

Phase 7: Response handling

✅ Verified live response shape:

{
  "data": {
    "audio": "<hex string, OR a download URL when output_format=url>",
    "status": 2,
    "subtitle_file": "<URL, present when subtitle_enable=true>"
  },
  "extra_info": {
    "audio_length": 4441,
    "audio_sample_rate": 44100,
    "audio_size": 0,
    "bitrate": 256000,
    "word_count": 43,
    "invisible_character_ratio": 0,
    "usage_characters": 43,
    "audio_format": "wav",
    "audio_channel": 1
  },
  "trace_id": "06c11f53...",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

Key facts, all verified:

• output_format: "url" puts the URL in data.audio itself — there is no separate audio_url field. The default is hex, which puts hex-encoded bytes in the same field. Always set output_format explicitly so you know which you are parsing.
• URLs are valid 24 hours — download immediately.
• data.status: 1 = synthesizing, 2 = complete.
• extra_info.audio_length is milliseconds — use it for timeline math.
• extra_info.audio_size can read 0 even for a valid file. Do not use it as a sanity check.
• extra_info.usage_characters is what you are billed for.
• An undocumented empty data.ced field is also returned. Ignore it.
• Always check base_resp.status_code == 0. HTTP 200 does not imply success.

# hex (default)
jq -r '.data.audio' resp.json | xxd -r -p > out.mp3
# url
jq -r '.data.audio' resp.json | xargs curl -sL -o out.wav

Error codes

Rate limits: T2A 60 RPM · Voice Cloning 60 RPM · Voice Design 20 RPM · async query 10 QPS.

Common failures and fixes

Supporting files

• Complete API reference — every parameter, async endpoints, file upload, full schemas
• Voice catalogue — all 332 preset voice IDs by language