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

パラメータと使用方法は公式に合わせています。詳細なパラメータは公式ドキュメントを直接参照してください。

## 1. 概要

本書では、MiniMax Speech の純正プロトコルを通じて、同期音声合成、非同期長文音声合成、ファイル管理、ボイスクイッククローン、ボイスデザインを使用する方法を説明します。

同期インターフェースは 1 回の POST リクエストで音声または SSE を直接返します。非同期インターフェースは先に task\_id を返し、呼び出し元がタスク状態を照会してから、file\_id を通じて結果ファイルを取得します。

### 1.1 エンドポイント

| 機能 | メソッドとパス |
| - | - |
| 同期音声合成 | POST /v3/minimax/v1/t2a\_v2 |
| 非同期音声タスクの作成 | POST /v3/minimax/v1/t2a\_async\_v2 |
| 非同期音声タスクの照会 | GET /v3/minimax/v1/query/t2a\_async\_query\_v2?task\_id={task_id} |
| ファイルのアップロード | POST /v3/minimax/v1/files/upload |
| ファイルの照会 | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} |
| ファイルのダウンロード | GET /v3/minimax/v1/files/retrieve\_content?file\_id={file_id} |
| ボイスクイッククローン | POST /v3/minimax/v1/voice\_clone |
| ボイスデザイン | POST /v3/minimax/v1/voice\_design |

完全なアドレスは https\://\{api\_domain} に表内のパスを加えたものです。ここで \{api\_domain} は使用する API ドメインです。

### 1.2 認証

すべてのリクエストにはプラットフォームの API Key が必要です。JSON POST リクエストではさらに Content-Type を指定する必要があります：

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

ファイルアップロードは multipart/form-data を使用します。GET リクエストには Content-Type は不要です。

### 1.3 レスポンスとリソースアクセス

本インターフェースは MiniMax 純正のレスポンスフィールドとエラー構造を保持します。JSON レスポンスには通常 base\_resp.status\_code と base\_resp.status\_msg が含まれます。HTTP 200 は必ずしもビジネス上の成功を意味しないため、常に base\_resp.status\_code=0 を確認してください。

task\_id と file\_id は JavaScript の安全な整数範囲を超える可能性があるため、損失のない整数または文字列で保存してください。ファイル、タスク、プライベートボイスは、それらを作成したプラットフォームユーザーのみがアクセスできます。照会時には、リソース作成時と同じプラットフォーム API Key を使用してください。

## 2. 同期音声合成

公式パラメータ説明：[同期音声合成 HTTP](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http)

### 2.1 エンドポイントの呼び出し

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

よく使用するリクエストフィールド：

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| model | string | は | speech-2.8-hd または speech-2.8-turbo |
| text | string | は | 合成するテキスト。10,000 文字未満。3,000 文字を超える場合はストリーミング出力を推奨 |
| stream | boolean | いいえ | 純正 SSE を返すかどうか。デフォルトは false |
| voice\_setting | object | は | ボイス ID、速度、音量、ピッチ、感情などの設定 |
| audio\_setting | object | いいえ | サンプルレート、ビットレート、フォーマット、チャンネル設定 |
| language\_boost | string | いいえ | 言語を指定、または auto |
| output\_format | string | いいえ | hex（デフォルト）または url。ストリーミングでは hex のみ対応。URL の有効期間は 24 時間 |
| subtitle\_enable | boolean | いいえ | 字幕を返すかどうか。デフォルトは false |

pronunciation\_dict、timbre\_weights、voice\_modify、stream\_options などの純正拡張フィールドはそのまま転送されます。詳細な制約は MiniMax 公式ドキュメントに従ってください。

### 2.2 呼び出し例

```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"
  }'
```

ストリーミング呼び出しでは、stream=true を設定し、ストリーミング読み取りに対応したクライアント（例：curl -N）を使用するだけです。

### 2.3 レスポンス説明

```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"
  }
}
```

ストリーミングレスポンスは純正 SSE です。最終成功イベントの data.status は 2 で、使用量は extra\_info.usage\_characters にあります。

### 2.4 課金説明

上流が最終的に返す extra\_info.usage\_characters に基づいて課金され、課金単位は 10,000 文字ごとです。失敗したリクエスト、純正のビジネスエラー、および正常終了イベントのない SSE は課金されません。具体的な単価は、使用するサービスの価格ページに準じます。

## 3. 非同期長文音声合成

公式パラメータ説明：[非同期タスクの作成](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create)、[非同期タスクの照会](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query)

### 3.1 タスクの作成

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

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| model | string | は | speech-2.8-hd または speech-2.8-turbo |
| text | string | 二者択一 | 合成するテキスト。最大 50,000 文字。text\_file\_id と二者択一 |
| text\_file\_id | integer | 二者択一 | ファイルアップロードで取得。txt または zip に対応。1 ファイルあたりのテキストは 1,000,000 文字未満 |
| voice\_setting | object | は | ボイスと音声パラメータ |
| audio\_setting | object | いいえ | 出力音声設定 |
| language\_boost | string | いいえ | 言語を指定、または auto |

### 3.2 作成例

```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"
  }
}
```

task\_id を保存してください。非同期タスクの作成成功時点で、レスポンス内の usage\_characters に基づいて課金されます。以降の照会では重複課金されません。

### 3.3 タスクの照会

```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>'
```

この照会インターフェースは 1 秒あたり最大 10 回呼び出せます。状態には Processing、Success、Failed、Expired があります。終端状態に達したらポーリングを停止してください。

```json theme={null}
{
  "task_id": 95157322514444,
  "status": "Success",
  "file_id": 95157322514496,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

タスク成功後、file\_id を使用してファイルを照会またはダウンロードします。MiniMax 公式によると、ダウンロード URL は生成から約 9 時間有効です。結果は速やかに保存してください。

## 4. ファイル管理

公式パラメータ説明：[ファイルのアップロード](https://platform.minimaxi.com/docs/api-reference/file-management-upload)、[ファイルの照会](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve)、[ファイルのダウンロード](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content)

### 4.1 ファイルのアップロード

```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 | 用途とフォーマット |
| - | - |
| voice\_clone | クイッククローン用の元音声。mp3、m4a、wav |
| prompt\_audio | ボイスクローン用のサンプル音声。mp3、m4a、wav |
| t2a\_async\_input | 非同期長文入力。txt、zip |

リクエストには purpose を 1 つ、ファイルを 1 つだけ含める必要があります。1 回のプラットフォームリクエストのボディ上限は 64 MiB ですが、MiniMax による用途ごとのフォーマット、長さ、サイズの制限は引き続き適用されます。

### 4.2 照会とダウンロード

```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 はファイルのメタデータと download\_url を返します。retrieve\_content はバイナリファイルを直接返します。アップロード、照会、ダウンロードは課金されません。

## 5. ボイスクイッククローン

公式パラメータ説明：[ボイスクイッククローン](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone)

### 5.1 エンドポイントとフィールド

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

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| file\_id | integer | は | purpose=voice\_clone でアップロードして取得したファイル ID。音声は 10 秒から 5 分、20 MB 以下 |
| voice\_id | string | は | カスタムボイス ID。長さ 8–256、英字で始まり、既存 ID と重複不可 |
| clone\_prompt | object | いいえ | サンプル音声。使用する場合、prompt\_audio と prompt\_text は両方必須 |
| text | string | いいえ | 試聴テキスト。最大 1,000 文字 |
| model | string | 条件付き必須 | text を渡す場合は必須。speech-2.8-hd または speech-2.8-turbo を使用 |
| text\_validation | string | いいえ | サンプルの想定テキスト。最大 200 文字 |
| accuracy | number | いいえ | ASR 類似度しきい値。0–1、デフォルトは 0.7 |

### 5.2 呼び出し例とレスポンス

```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"
  }
}
```

成功したリクエストは 1 ボイスとして課金されます。リクエスト内で試聴音声を生成しても、プラットフォームは音声合成 SKU を追加しません。MiniMax 公式によると、クローンしたボイスが 7 日以内に正式に音声合成で使用されない場合、削除される可能性があります。

## 6. ボイスデザイン

公式パラメータ説明：[ボイスデザイン](https://platform.minimaxi.com/docs/api-reference/voice-design-design)

### 6.1 エンドポイントとフィールド

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

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| prompt | string | は | 対象ボイスの説明 |
| preview\_text | string | は | 試聴テキスト。最大 500 文字 |
| voice\_id | string | いいえ | カスタムボイス ID。指定しない場合は MiniMax が生成 |
| aigc\_watermark | boolean | いいえ | 試聴音声の末尾にリズム識別子を追加するかどうか。デフォルトは false |

### 6.2 呼び出し例とレスポンス

```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"
  }
}
```

成功したリクエストは 1 ボイスとして課金され、試聴音声は今回のインターフェース課金に含まれます。音声合成 SKU は追加されません。

## 7. よくあるエラーと注意事項

| 現象 | 説明と対処方法 |
| - | - |
| HTTP 200 だが base\_resp.status\_code!=0 | MiniMax のビジネスエラー。status\_msg に従って入力を修正し、成功として扱わないでください |
| HTTP 400 | JSON、multipart、モデル名、クエリパラメータ、または必須フィールドが不正です |
| HTTP 401/403 | プラットフォーム API Key、残高、権限を確認してください |
| HTTP 404 | ファイル、タスク、またはプライベートボイスが存在しないか、現在のプラットフォームユーザーに属していません |
| HTTP 429 | リクエスト/照会の頻度を下げ、指数バックオフを使用してください。非同期照会は 1 秒あたり 10 回を超えてはいけません |
| HTTP 5xx | レスポンスとプラットフォームの trace ID を保持してテクニカルサポートに連絡してください。非冪等な作成リクエストを無制御に再試行しないでください |

* 純正フィールドは可能な限りそのまま転送されますが、本サービスは本書に記載された 8 つのパスのみを公開します。
* 1 回のリクエストボディおよび 1 つの SSE イベントの上限は 64 MiB です。
* クライアントが切断した後も、使用量の決済を完了するために、開始済みの SSE をサービスが読み取り続ける場合があります。
* 非同期タスクの状態は、本書の MiniMax 照会インターフェースを通じて取得する必要があります。プラットフォームの汎用非同期結果インターフェースは使用しません。
* ファイル URL または成功したファイル ID を受け取ったら、速やかにダウンロードしてください。URL とファイルは期限切れになる可能性があります。

## 8. Python 呼び出し例

以下の例では、非同期作成とポーリングを示します。本番環境では、全体のタイムアウト、指数バックオフ、最大ポーリング回数を設定してください。

```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.