MiniMax Speech Text-to-Speech API - speech-2.8

Synthesize speech from text, voice, and audio parameters. Supports streaming and non-streaming, with hex or URL output.

Call MiniMax Speech to synthesize audio from text. Supports system voices, cloned voices, speed/volume/pitch, emotion, voice mixing, subtitles, and streaming output.

Non-streaming defaults to hex-encoded audio; set output_format to url to receive a downloadable link (valid for 24 hours). Streaming supports hex only.

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) Authenticate using a Bearer Token. Format: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/v1/t2a_v2`

Create Text-to-Speech Request

Pass text, a voice, and audio settings. Returns audio data or an audio URL.

Request Body

Content-Type: application/json

Example:

{
  "model": "speech-2.8-hd",
  "text": "今天是不是很开心呀(laughs)，当然了！",
  "stream": false,
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  },
  "pronunciation_dict": {
    "tone": [
      "处理/(chu3)(li3)",
      "危险/dangerous"
    ]
  },
  "subtitle_enable": false
}

Properties:

Name	Type	Required	Description
`model`	string	Yes	Model name. Available values: `speech-2.8-hd`, `speech-2.6-hd`, `speech-02-hd`, `speech-2.8-turbo`, `speech-2.6-turbo`, `speech-02-turbo`
`text`	string	Yes	Text to synthesize, fewer than 10,000 characters. Use newlines to segment. Pause marker is `<#x#>`, where `x` is seconds in `[0.01, 99.99]` with up to two decimal places, and must be wrapped by pronounceable text. `speech-2.8-hd` / `speech-2.8-turbo` support tone tags such as `(laughs)`, `(chuckle)`, `(coughs)`, `(sighs)`
`stream`	boolean	No	Whether to stream output. Default `false`
`stream_options`	object	No	Streaming options
`stream_options.exclude_aggregated_audio`	boolean	No	Whether the final chunk excludes the concatenated full hex audio. Default `false` (the final chunk includes the full audio)
`voice_setting`	object	No	Voice and reading controls
`audio_setting`	object	No	Output audio parameters
`pronunciation_dict`	object	No	Pronunciation replacement rules
`timber_weights`	object[]	No	Mixed-voice weights, up to 4. When using this field, leave `voice_setting.voice_id` empty
`language_boost`	string \| null	No	Language boost, e.g. `Chinese`, `English`, `auto`. Default `null`
`voice_modify`	object	No	Pitch/intensity/timbre fine-tuning and sound effects
`subtitle_enable`	boolean	No	Whether to enable subtitles. Non-streaming only. Default `false`
`output_format`	string	No	Non-streaming output form: `hex` (default) or `url`. Streaming supports `hex` only. URL valid for 24 hours
`aigc_watermark`	boolean	No	Whether to append a rhythmic marker at the end of the audio. Non-streaming only. Default `false`

voice_settingobject(Optional)

Voice and reading controls. Supports system voices, cloned voices, and text-generated voices.

voice_idstring(Optional)

Voice ID used for synthesis. Leave empty when mixing with timber_weights.

speednumber(Optional)

Speech rate in [0.5, 2]. Default 1. Higher is faster.

volnumber(Optional)

Volume in (0, 10]. Default 1.

pitchinteger(Optional)

Pitch in [-12, 12]. Default 0 (original voice pitch).

emotionstring(Optional)

Emotion. Available values: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper.

text_normalizationboolean(Optional)

Whether to enable Chinese/English text normalization. Improves number reading and may slightly increase latency. Default false.

latex_readboolean(Optional)

Whether to read LaTeX formulas. Chinese only; enabling this sets language_boost to Chinese. Wrap formulas in $$ and escape backslashes. Default false.

audio_settingobject(Optional)

Output audio parameters.

sample_rateinteger(Optional)

Sample rate. Available values: 8000, 16000, 22050, 24000, 32000 (default), 44100.

bitrateinteger(Optional)

Bitrate. Applies to MP3 only. Available values: 32000, 64000, 128000 (default), 256000.

formatstring(Optional)

Audio format: mp3 (default), pcm, flac, wav. wav is non-streaming only.

channelinteger(Optional)

Number of channels. 1 mono (default), 2 stereo.

force_cbrboolean(Optional)

Constant bitrate encoding. Applies only when streaming with format mp3.

timber_weightsobject[](Optional)

Mixed-voice weights, up to 4 voices. When used, leave voice_setting.voice_id empty.

voice_idstring(Required)

Voice ID included in the mix.

weightinteger(Required)

Weight of this voice in [1, 100]. Higher values stay closer to this voice.

voice_modifyobject(Optional)

Pitch, intensity, timbre fine-tuning, and sound effects. Only one sound effect can be selected per request.

pitchinteger(Optional)

Pitch adjustment in [-100, 100]. Closer to -100 is deeper; closer to 100 is brighter.

intensityinteger(Optional)

Intensity adjustment in [-100, 100]. Closer to -100 is stronger; closer to 100 is softer.

timbreinteger(Optional)

Timbre adjustment in [-100, 100]. Closer to -100 is thicker; closer to 100 is clearer.

sound_effectsstring(Optional)

Sound effect. Select only one: spacious_echo, auditorium_echo, lofi_telephone, robotic.

Responses

200: Synthesis succeeded

Content-Type: application/json

400: Request failed (see base_resp.status_code)

Content-Type: application/json

Request Example

curl -X POST "https://api.autorouter.top/v1/t2a_v2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "speech-2.8-hd",
  "text": "今天是不是很开心呀(laughs)，当然了！",
  "stream": false,
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  }
}'

Response Example

{
  "data": {
    "audio": "<hex编码的audio>",
    "status": 2
  },
  "extra_info": {
    "audio_length": 9900,
    "audio_sample_rate": 32000,
    "audio_size": 160323,
    "bitrate": 128000,
    "word_count": 52,
    "invisible_character_ratio": 0,
    "usage_characters": 26,
    "audio_format": "mp3",
    "audio_channel": 1
  },
  "trace_id": "01b8bf9bb7433cc75c18eee6cfa8fe21",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Response fields:

Name	Type	Description
`data`	object \| null	Audio data. May be `null` on failure; check before use
`data.audio`	string	Synthesized audio. Hex by default; a URL when `output_format: url`
`data.subtitle_file`	string	Subtitle download URL. Sentence-level, max 50 characters, millisecond timestamps, JSON format
`data.status`	integer	Audio stream status. `1` synthesizing, `2` finished
`extra_info`	object	Audio metadata
`extra_info.audio_length`	integer	Audio duration in milliseconds
`extra_info.audio_sample_rate`	integer	Sample rate
`extra_info.audio_size`	integer	File size in bytes
`extra_info.bitrate`	integer	Bitrate
`extra_info.audio_format`	string	Audio format: `mp3` / `pcm` / `flac`
`extra_info.audio_channel`	integer	Channel count. `1` mono, `2` stereo
`extra_info.invisible_character_ratio`	number	Invalid character ratio. Generation still proceeds at or below 10%; above 10% returns an error
`extra_info.usage_characters`	integer	Billable character count
`extra_info.word_count`	integer	Pronounced character count (Chinese characters, digits, and letters; excludes punctuation)
`trace_id`	string	Session ID for support or feedback
`base_resp.status_code`	integer	Status code. `0` success; error codes include `1000`, `1001`, `1002`, `1004`, `1039`, `1042`, `2013`
`base_resp.status_msg`	string	Status message

Error Handling

HTTP 400 Parameter Errors

Scenario	Response
Invalid input parameters	`{"data":null,"trace_id":"...","base_resp":{"status_code":2013,"status_msg":"输入参数信息不正常"}}`
Invalid character ratio exceeds 10%	`base_resp.status_code` is non-zero and `data` is `null`

HTTP 401 / 403 Auth Errors

401 Unauthorized: API Key invalid or expired
403 Forbidden: API Key has no access to this model (check token's model allowlist)

HTTP 402 Insufficient Balance

Returns insufficient user quota. Top up at the AutoRouter console.

Before using the response, check whether data is null, and treat base_resp.status_code == 0 as business success.

Text to Speech

Base URL

Authentication

Endpoints

POST `/v1/t2a_v2`

Request Body

voice_settingobject(Optional)

audio_settingobject(Optional)

timber_weightsobject[](Optional)

voice_modifyobject(Optional)

Responses

Request Example

Response Example

Error Handling

HTTP 400 Parameter Errors

HTTP 401 / 403 Auth Errors

HTTP 402 Insufficient Balance

On this page