MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

minimax

t2a_v2

MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Parameters and usage align with the official specifications. For detailed parameters, refer directly to the official documentation.

1. Overview

This document explains how to use synchronous speech synthesis, asynchronous long-text speech synthesis, file management, fast voice cloning, and voice design through the native MiniMax Speech protocol. The synchronous endpoint returns audio or SSE directly in a single POST request; the asynchronous endpoint first returns a task_id, and the caller then queries the task status and retrieves the result file via file_id.

1.1 API Endpoints

Capability	Method and Path
Synchronous speech synthesis	POST /v3/minimax/v1/t2a_v2
Create asynchronous speech task	POST /v3/minimax/v1/t2a_async_v2
Query asynchronous speech task	GET /v3/minimax/v1/query/t2a_async_query_v2?task_id=
Upload file	POST /v3/minimax/v1/files/upload
Query file	GET /v3/minimax/v1/files/retrieve?file_id=
Download file	GET /v3/minimax/v1/files/retrieve_content?file_id=
Fast voice cloning	POST /v3/minimax/v1/voice_clone
Voice design	POST /v3/minimax/v1/voice_design

The full URL is https://{api_domain} plus the path in the table, where {api_domain} is the API domain you use.

1.2 Authentication

All requests require a platform API Key. JSON POST requests must also specify the content type:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

File uploads use multipart/form-data; GET requests do not require Content-Type.

1.3 Responses and Resource Access

The API preserves the native MiniMax response fields and error structure. JSON responses usually contain base_resp.status_code and base_resp.status_msg; HTTP 200 does not necessarily indicate business success, so always check base_resp.status_code=0. task_id and file_id may exceed the JavaScript safe integer range, so store them as lossless integers or strings. Files, tasks, and private voices can only be accessed by the platform user who created them; when querying, use the same platform API Key that was used to create the resource.

2. Synchronous Speech Synthesis

Official parameter reference: Synchronous Speech Synthesis HTTP

2.1 Calling the Endpoint

POST https://{api_domain}/v3/minimax/v1/t2a_v2

Common request fields:

Field	Type	Required	Description
model	string	Yes	speech-2.8-hd or speech-2.8-turbo
text	string	Yes	Text to synthesize, fewer than 10,000 characters; for more than 3,000 characters, streaming output is recommended
stream	boolean	No	Whether to return native SSE; default false
voice_setting	object	Yes	Settings such as voice ID, speed, volume, pitch, and emotion
audio_setting	object	No	Sample rate, bitrate, format, and channel settings
language_boost	string	No	Specify a language or auto
output_format	string	No	hex (default) or url; streaming supports only hex; URLs are valid for 24 hours
subtitle_enable	boolean	No	Whether to return subtitles; default false

Native extension fields such as pronunciation_dict, timbre_weights, voice_modify, and stream_options are forwarded as-is; refer to the official MiniMax documentation for detailed constraints.

2.2 Example Call

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-hd",
    "text": "Welcome to our service.",
    "stream": false,
    "voice_setting": {
      "voice_id": "male-qn-qingse",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    },
    "output_format": "url"
  }'

For streaming calls, just set stream=true and use a client that supports streaming reads, such as curl -N.

2.3 Response Description

{
  "data": {
    "audio": "https://example.com/audio.mp3",
    "status": 2
  },
  "extra_info": {
    "usage_characters": 26,
    "audio_length": 9900,
    "audio_format": "mp3"
  },
  "trace_id": "provider-trace-id",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Streaming responses use native SSE. The data.status of the final success event is 2, and usage is in extra_info.usage_characters.

2.4 Billing

Billing is based on the extra_info.usage_characters returned by the upstream service, in units of 10,000 characters. Failed requests, native business errors, and SSE responses without a successful termination event are not charged. For specific pricing, refer to the pricing page of the service you use.

3. Asynchronous Long-Text Speech Synthesis

Official parameter reference: Create Asynchronous Task, Query Asynchronous Task

3.1 Create a Task

POST https://{api_domain}/v3/minimax/v1/t2a_async_v2

Field	Type	Required	Description
model	string	Yes	speech-2.8-hd or speech-2.8-turbo
text	string	Choose one	Text to synthesize, up to 50,000 characters; choose either this or text_file_id
text_file_id	integer	Choose one	Obtained via file upload; supports txt or zip; text per file must be under 1,000,000 characters
voice_setting	object	Yes	Voice and speech parameters
audio_setting	object	No	Output audio settings
language_boost	string	No	Specify a language or auto

3.2 Create Example

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_async_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-turbo",
    "text": "A longer narration.",
    "voice_setting": {
      "voice_id": "audiobook_male_1",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    }
  }'

{
  "task_id": 95157322514444,
  "task_token": "provider-task-token",
  "file_id": 95157322514444,
  "usage_characters": 101,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Save the task_id. When an asynchronous task is successfully created, you are charged based on the usage_characters in the response; subsequent queries are not charged again.

3.3 Query a Task

curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

This query endpoint can be called at most 10 times per second. Statuses include Processing, Success, Failed, and Expired; stop polling once a terminal state is reached.

{
  "task_id": 95157322514444,
  "status": "Success",
  "file_id": 95157322514496,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

After the task succeeds, use file_id to query or download the file. MiniMax’s official documentation states that download URLs are valid for about 9 hours from generation, so save the results promptly.

4. File Management

Official parameter reference: File Upload, File Retrieval, File Download

4.1 Upload a File

curl -X POST 'https://{api_domain}/v3/minimax/v1/files/upload' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'purpose=voice_clone' \
  -F 'file=@voice.wav'

purpose	Use and Format
voice_clone	Raw audio for fast cloning; mp3, m4a, wav
prompt_audio	Voice cloning sample audio; mp3, m4a, wav
t2a_async_input	Asynchronous long-text input; txt, zip

The request must contain exactly one purpose and one file. The maximum size of a single platform request body is 64 MiB; MiniMax’s format, duration, and size limits for each purpose still apply.

4.2 Query and Download

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve_content?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  --output result.mp3

retrieve returns file metadata and download_url; retrieve_content returns the binary file directly. Uploads, queries, and downloads are not charged.

5. Fast Voice Cloning

Official parameter reference: Fast Voice Cloning

5.1 Endpoint and Fields

POST https://{api_domain}/v3/minimax/v1/voice_clone

Field	Type	Required	Description
file_id	integer	Yes	File ID obtained by uploading with purpose=voice_clone; audio must be 10 seconds to 5 minutes and no larger than 20 MB
voice_id	string	Yes	Custom voice ID, length 8–256, starts with a letter, must not duplicate an existing ID
clone_prompt	object	No	Sample audio; when used, both prompt_audio and prompt_text are required
text	string	No	Preview text, up to 1,000 characters
model	string	Conditionally required	Required when text is passed; use speech-2.8-hd or speech-2.8-turbo
text_validation	string	No	Expected text of the sample, up to 200 characters
accuracy	number	No	ASR similarity threshold, 0–1, default 0.7

5.2 Example Call and Response

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_clone' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyVoice001",
    "need_noise_reduction": false,
    "need_volume_normalization": false
  }'

{
  "input_sensitive": false,
  "demo_audio": "",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

A successful request is billed as one voice. If preview audio is generated in the request, the platform does not add an additional speech synthesis SKU. MiniMax’s official documentation states that cloned voices may be deleted if they are not formally used for speech synthesis within 7 days.

6. Voice Design

Official parameter reference: Voice Design

6.1 Endpoint and Fields

POST https://{api_domain}/v3/minimax/v1/voice_design

Field	Type	Required	Description
prompt	string	Yes	Description of the target voice
preview_text	string	Yes	Preview text, up to 500 characters
voice_id	string	No	Custom voice ID; if not provided, MiniMax generates one
aigc_watermark	boolean	No	Whether to add a rhythm marker at the end of the preview audio; default false

6.2 Example Call and Response

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_design' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A warm, clear adult narrator with a calm delivery.",
    "preview_text": "Welcome to our service."
  }'

{
  "voice_id": "ttv-voice-generated-id",
  "trial_audio": "hex-encoded-audio",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

A successful request is billed as one voice; the preview audio is included in this API’s billing and does not add an additional speech synthesis SKU.

7. Common Errors and Notes

Symptom	Description and Recommended Action
HTTP 200 but base_resp.status_code!=0	MiniMax business error; correct the input according to status_msg and do not treat it as success
HTTP 400	Invalid JSON, multipart, model name, query parameters, or required fields
HTTP 401/403	Check the platform API Key, balance, and permissions
HTTP 404	The file, task, or private voice does not exist or does not belong to the current platform user
HTTP 429	Reduce request/query frequency and use exponential backoff; asynchronous queries must not exceed 10 per second
HTTP 5xx	Keep the response and platform trace ID, then contact technical support; do not retry non-idempotent create requests without control

Native fields are forwarded as-is where possible, but this service exposes only the eight paths listed in this document.
The maximum size of a single request body and a single SSE event is 64 MiB.
After the client disconnects, the service may continue reading an SSE stream that has already started in order to complete usage settlement.
Asynchronous tasks must use the MiniMax query endpoint in this document to obtain status; do not use the platform’s generic asynchronous result endpoint.
Download files promptly after receiving a file URL or a successful file ID; URLs and files may expire.

8. Python Example

The following example demonstrates asynchronous creation and polling. In production, set an overall timeout, exponential backoff, and a maximum number of polling attempts.

import os
import time

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"https://{api_domain}/v3/minimax/v1/t2a_async_v2",
    headers=headers,
    json={
        "model": "speech-2.8-turbo",
        "text": "A longer narration.",
        "voice_setting": {"voice_id": "audiobook_male_1"},
    },
    timeout=60,
)
created.raise_for_status()
created_body = created.json()
if created_body["base_resp"]["status_code"] != 0:
    raise RuntimeError(created_body)
task_id = created_body["task_id"]

while True:
    response = requests.get(
        f"https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"task_id": task_id},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()
    if task["base_resp"]["status_code"] != 0:
        raise RuntimeError(task)
    if task["status"] == "Success":
        print(task["file_id"])
        break
    if task["status"] in {"Failed", "Expired"}:
        raise RuntimeError(task)
    time.sleep(2)

Last modified on October 21, 2026

API Basics

API Key Management

Large Language Models

Images

Video

Audio

MiniMax Speech

1. Overview

1.1 API Endpoints

1.2 Authentication

1.3 Responses and Resource Access

2. Synchronous Speech Synthesis

2.1 Calling the Endpoint

2.2 Example Call

2.3 Response Description

2.4 Billing

3. Asynchronous Long-Text Speech Synthesis

3.1 Create a Task

3.2 Create Example

3.3 Query a Task

4. File Management

4.1 Upload a File

4.2 Query and Download

5. Fast Voice Cloning

5.1 Endpoint and Fields

5.2 Example Call and Response

6. Voice Design

6.1 Endpoint and Fields

6.2 Example Call and Response

7. Common Errors and Notes

8. Python Example

​1. Overview

​1.1 API Endpoints

​1.2 Authentication

​1.3 Responses and Resource Access

​2. Synchronous Speech Synthesis

​2.1 Calling the Endpoint

​2.2 Example Call

​2.3 Response Description

​2.4 Billing

​3. Asynchronous Long-Text Speech Synthesis

​3.1 Create a Task

​3.2 Create Example

​3.3 Query a Task

​4. File Management

​4.1 Upload a File

​4.2 Query and Download

​5. Fast Voice Cloning

​5.1 Endpoint and Fields

​5.2 Example Call and Response

​6. Voice Design

​6.1 Endpoint and Fields

​6.2 Example Call and Response

​7. Common Errors and Notes

​8. Python Example

1. Overview

1.1 API Endpoints

1.2 Authentication

1.3 Responses and Resource Access

2. Synchronous Speech Synthesis

2.1 Calling the Endpoint

2.2 Example Call

2.3 Response Description

2.4 Billing

3. Asynchronous Long-Text Speech Synthesis

3.1 Create a Task

3.2 Create Example

3.3 Query a Task

4. File Management

4.1 Upload a File

4.2 Query and Download

5. Fast Voice Cloning

5.1 Endpoint and Fields

5.2 Example Call and Response

6. Voice Design

6.1 Endpoint and Fields

6.2 Example Call and Response

7. Common Errors and Notes

8. Python Example