> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax Speech

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={task_id} |
| Upload file | POST /v3/minimax/v1/files/upload |
| Query file | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} |
| Download file | GET /v3/minimax/v1/files/retrieve\_content?file\_id={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](https://platform.minimaxi.com/docs/api-reference/speech-t2a-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

```bash theme={null}
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

```json theme={null}
{
  "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](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create), [Query Asynchronous Task](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query)

### 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

```bash theme={null}
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
    }
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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.

```json theme={null}
{
  "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](https://platform.minimaxi.com/docs/api-reference/file-management-upload), [File Retrieval](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve), [File Download](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content)

### 4.1 Upload a File

```bash theme={null}
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

```bash theme={null}
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](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone)

### 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

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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](https://platform.minimaxi.com/docs/api-reference/voice-design-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

```bash theme={null}
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."
  }'
```

```json theme={null}
{
  "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.

```python theme={null}
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)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.