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

# MiniMax Speech

`POST https://api.novita.ai/v3/minimax-en/v1/t2a_v2`

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

## 1. Overview

This document describes how to use the MiniMax Speech (overseas edition) native protocol: speech recognition, synchronous text-to-speech, asynchronous long-text text-to-speech, file management, voice cloning, and voice design.

All requests use the same host `https://{api_domain}`, where `{api_domain}` is the API domain provided to you by the platform. Every request must carry the platform API key:

```text theme={"system"}
Authorization: Bearer <YOUR_API_KEY>
```

Requests with a JSON body must also set `Content-Type: application/json`; file-related requests use `multipart/form-data`.

| Capability | Method and path |
| - | - |
| Speech recognition | `POST /v3/minimax-en/v1/speech_to_text` |
| Synchronous text-to-speech | `POST /v3/minimax-en/v1/t2a_v2` |
| Create an asynchronous text-to-speech task | `POST /v3/minimax-en/v1/t2a_async_v2` |
| Query an asynchronous text-to-speech task | `GET /v3/minimax-en/v1/query/t2a_async_query_v2?task_id={task_id}` |
| Upload a file | `POST /v3/minimax-en/v1/files/upload` |
| Retrieve file information | `GET /v3/minimax-en/v1/files/retrieve?file_id={file_id}` |
| Download a file | `GET /v3/minimax-en/v1/files/retrieve_content?file_id={file_id}` |
| Voice cloning | `POST /v3/minimax-en/v1/voice_clone` |
| Voice design | `POST /v3/minimax-en/v1/voice_design` |

## 2. Official references

* Speech recognition: [https://platform.minimax.io/docs/api-reference/speech-to-text](https://platform.minimax.io/docs/api-reference/speech-to-text)
* Synchronous text-to-speech: [https://platform.minimax.io/docs/api-reference/speech-t2a-http](https://platform.minimax.io/docs/api-reference/speech-t2a-http)
* Asynchronous text-to-speech: [https://platform.minimax.io/docs/api-reference/speech-t2a-async-create](https://platform.minimax.io/docs/api-reference/speech-t2a-async-create)
* Voice cloning: [https://platform.minimax.io/docs/api-reference/voice-cloning-clone](https://platform.minimax.io/docs/api-reference/voice-cloning-clone)
* Voice design: [https://platform.minimax.io/docs/api-reference/voice-design-design](https://platform.minimax.io/docs/api-reference/voice-design-design)

## 3. Supported models

| Model | Notes |
| - | - |
| MiniMax Speech to Text | See the official documentation for the exact model name used in requests |
| MiniMax Speech 2.8 HD | `speech-2.8-hd` |
| MiniMax Speech 2.8 Turbo | `speech-2.8-turbo` |

## 4. Speech recognition

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/speech_to_text
```

```bash theme={"system"}
curl -X POST 'https://{api_domain}/v3/minimax-en/v1/speech_to_text' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'language: en' \
  -F 'model=asr-1.0' \
  -F 'response_format=verbose_json' \
  -F 'file=@meeting.mp3'
```

The audio file is uploaded as `multipart/form-data`, and the recognition language is passed in the `language` header.

## 5. Synchronous text-to-speech

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/t2a_v2
```

```bash theme={"system"}
curl -X POST 'https://{api_domain}/v3/minimax-en/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": "English_expressive_narrator",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    },
    "output_format": "url"
  }'
```

Set `stream` to `true` when you need streaming output. `output_format` controls whether the audio is returned as a URL or as Base64 data.

## 6. Asynchronous long-text text-to-speech

Long text is synthesized as a task: create the task first, then poll the query endpoint with the returned task ID.

### 6.1 Create a task

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/t2a_async_v2
```

```bash theme={"system"}
curl -X POST 'https://{api_domain}/v3/minimax-en/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": "English_expressive_narrator",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    }
  }'
```

### 6.2 Query a task

```text theme={"system"}
GET https://{api_domain}/v3/minimax-en/v1/query/t2a_async_query_v2?task_id={task_id}
```

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

## 7. File management

Files are used by voice cloning and by other MiniMax capabilities that accept a `file_id`. Upload the file first to obtain its `file_id`.

### 7.1 Upload a file

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/files/upload
```

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

`purpose` declares how the file will be used; use `voice_clone` for a voice sample.

### 7.2 Retrieve file information

```text theme={"system"}
GET https://{api_domain}/v3/minimax-en/v1/files/retrieve?file_id={file_id}
```

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

### 7.3 Download a file

```text theme={"system"}
GET https://{api_domain}/v3/minimax-en/v1/files/retrieve_content?file_id={file_id}
```

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

## 8. Voice cloning

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/voice_clone
```

```bash theme={"system"}
curl -X POST 'https://{api_domain}/v3/minimax-en/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
  }'
```

`file_id` is the ID returned by the upload endpoint. `voice_id` is the custom voice ID you assign, and it can be used as `voice_setting.voice_id` in text-to-speech requests afterwards.

## 9. Voice design

```text theme={"system"}
POST https://{api_domain}/v3/minimax-en/v1/voice_design
```

```bash theme={"system"}
curl -X POST 'https://{api_domain}/v3/minimax-en/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."
  }'
```

`prompt` describes the voice to design, and `preview_text` is the sample text used to preview the generated voice.


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