# MiniMax-文字转语音（T2A）

将口播文案合成为音频，可选返回**字幕文件链接**，用于 **混剪配音、数字人口播、字幕轨对齐** 等场景。

与 ASR 的配合：混剪常见流程为 **T2A 生成口播音频 + 字幕** → 成片后再用 [录音文件 ASR（极速版）](/api-asr-flash-doubao) 做校对或拆条（视业务而定）。

<div class="doc-interface">
  <p><strong>URL</strong>：<code>$BASE_URL/v1/t2a_v2</code></p>
  <p><strong>Method</strong>：<code>POST</code></p>
  <p><strong>Content-Type</strong>：<code>application/json</code></p>
  <p><strong>平台模型</strong>：<code>speech-2.8-hd</code>（请求体 <code>model</code> 字段须与此一致）</p>
</div>

<div class="doc-api-spec">

## aisee 混剪用哪个接口？

aisee 等业务侧通过 **`amagssdk.CreateT2A`** 调用本平台，底层即：

```http
POST $BASE_URL/v1/t2a_v2
Authorization: Bearer $API_KEY
```

**不是** WebSocket，**不是** `/v3/...` 路径。混剪配音推荐：

| 项 | 推荐值 |
|----|--------|
| 接口 | `POST /v1/t2a_v2` |
| 模型 | `speech-2.8-hd` |
| `stream` | `false`（一次性拿完整 JSON + 字幕链接） |
| `subtitle_enable` | `true`（返回 `data.subtitle_file`） |
| `subtitle_type` | `sentence`（句级字幕，便于上轴） |
| 响应 | JSON，`data.audio` 为 hex 音频，`data.subtitle_file` 为字幕 JSON 地址 |

长文案、需边合成边播放时可设 `stream: true`（SSE），见下文「流式合成」。

## 鉴权

公共变量见 [API 接入 · 公共参数](/api-common)。

| 方式 | 说明 |
|------|------|
| `Authorization: Bearer $API_KEY` | **推荐** |
| `x-api-key: $API_KEY` | 兼容 Anthropic / OpenAI 风格客户端 |

API Key 需 **scope 为 `chat` 或 `all`**，且租户 **可用余额 &gt; 0**。

## 请求体（MiniMax 官方格式 · 混剪推荐）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | **是** | 填 `speech-2.8-hd` |
| `text` | string | **是** | 待合成文案（与 `input` 二选一，混剪用 `text`） |
| `stream` | bool | 否 | 默认 `false`；`true` 时为 SSE 流式 |
| `output_format` | string | 否 | 非流式建议 `hex`（响应内嵌音频 hex） |
| `voice_setting` | object | 否 | 音色参数 |
| `voice_setting.voice_id` | string | 否 | MiniMax 音色 ID |
| `voice_setting.speed` | float | 否 | 语速，如 `1.0` |
| `voice_setting.vol` | float | 否 | 音量 |
| `voice_setting.pitch` | int | 否 | 音调 |
| `audio_setting` | object | 否 | 输出音频格式 |
| `audio_setting.format` | string | 否 | 如 `mp3`、`wav` |
| `audio_setting.sample_rate` | int | 否 | 如 `32000` |
| `subtitle_enable` | bool | 否 | **混剪建议 true** |
| `subtitle_type` | string | 否 | `sentence` / `word`；`word_streaming` 仅 `stream=true` |
| `language_boost` | string | 否 | 如 `Chinese` |

### 混剪请求示例

```json
{
  "model": "speech-2.8-hd",
  "text": "大家好，欢迎收看本期混剪口播。",
  "stream": false,
  "output_format": "hex",
  "voice_setting": {
    "voice_id": "Chinese_Internet_Lyrical_Voice",
    "speed": 1.0,
    "vol": 1.0,
    "pitch": 0
  },
  "audio_setting": {
    "format": "mp3",
    "sample_rate": 32000
  },
  "subtitle_enable": true,
  "subtitle_type": "sentence",
  "language_boost": "Chinese"
}
```

## 响应（非流式 · 含字幕）

HTTP 200，`Content-Type: application/json`：

```json
{
  "data": {
    "audio": "ffd8e0...",
    "subtitle_file": "https://example.com/subtitle.json",
    "status": 2
  },
  "extra_info": {
    "audio_length": 3500,
    "audio_sample_rate": 32000,
    "usage_characters": 42,
    "audio_format": "mp3"
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

| 字段 | 说明 |
|------|------|
| `data.audio` | hex 编码的音频，解码后写入 mp3/wav |
| `data.subtitle_file` | 句级字幕 JSON 的下载 URL（需 `subtitle_enable: true`） |
| `extra_info.usage_characters` | 计费字符数 |
| `extra_info.audio_length` | 音频时长（毫秒） |

### 解码音频

```bash
python -c "import json; d=json.load(open('response.json')); open('voice.mp3','wb').write(bytes.fromhex(d['data']['audio']))"
```

## CURL 示例

先设置 [公共变量](/api-common)：

```bash
BASE_URL="https://ai.open.thinkzoneai.com"
API_KEY="替换为你的API Key"
```

### 混剪口播 + 句级字幕（推荐）

```bash
curl -s -X POST "$BASE_URL/v1/t2a_v2" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "大家好，欢迎收看本期混剪口播。",
    "stream": false,
    "output_format": "hex",
    "voice_setting": {
      "voice_id": "Chinese_Internet_Lyrical_Voice",
      "speed": 1.0,
      "vol": 1.0,
      "pitch": 0
    },
    "audio_setting": {
      "format": "mp3",
      "sample_rate": 32000
    },
    "subtitle_enable": true,
    "subtitle_type": "sentence",
    "language_boost": "Chinese"
  }' \
  -o t2a-response.json
```

### 最简合成（无字幕）

```bash
curl -s -X POST "$BASE_URL/v1/t2a_v2" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "你好，这是一段测试。",
    "stream": false,
    "output_format": "hex",
    "voice_setting": { "voice_id": "Chinese_Female_Sharp" },
    "audio_setting": { "format": "mp3" }
  }'
```

### OpenAI 兼容（直接返回 mp3 字节）

仅 `input` + `voice` + `format`、且 **未开** `subtitle_enable` 时，响应可能为裸 `audio/mpeg`：

```bash
curl -s -X POST "$BASE_URL/v1/t2a_v2" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "input": "Hello, this is a test.",
    "voice": "alloy",
    "format": "mp3"
  }' \
  --output out.mp3
```

混剪场景请用 **官方格式 + `subtitle_enable`**，不要用纯 OpenAI 兼容路径。

## 流式合成（SSE）

长文案可设 `stream: true`，响应为 `text/event-stream`，事件体为 MiniMax SSE JSON（含分片 `data.audio` hex）。

```bash
curl -N -X POST "$BASE_URL/v1/t2a_v2" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "这是一段较长的口播文案……",
    "stream": true,
    "output_format": "hex",
    "voice_setting": { "voice_id": "Chinese_Internet_Lyrical_Voice" },
    "audio_setting": { "format": "mp3" }
  }'
```

浏览器测试页：`/t2a-stream-test.html`（部署后与站点同源访问）。

## Go SDK（aisee 同款）

```go
import (
    "code.keplerjai.com/keplerjai/campus-amags/pkg"
    "code.keplerjai.com/keplerjai/campus-amags/sdk/amagssdk"
)

// Init：amagssdk.Init(host); amagssdk.SetAPIKey(key)

subtitleEnable := true
result, err := amagssdk.CreateT2A(pkg.MiniMaxT2AReq{
    Model: "speech-2.8-hd",
    Text:  "大家好，欢迎收看本期混剪口播。",
    VoiceSetting: &pkg.MiniMaxT2AVoiceSetting{
        VoiceID: "Chinese_Internet_Lyrical_Voice",
    },
    AudioSetting: &pkg.MiniMaxT2AAudioSetting{
        Format:     "mp3",
        SampleRate: 32000,
    },
    SubtitleEnable: &subtitleEnable,
    SubtitleType:   "sentence",
    LanguageBoost:  "Chinese",
})
if err != nil { /* handle */ }

audio, _ := amagssdk.T2AAudioBytes(result)           // 写入 mp3
subtitleURL := result.Resp.Data.SubtitleFile        // 下载字幕 JSON 上轴
chars := result.Resp.ExtraInfo.UsageCharacters      // 计费字符
```

流式：`CreateT2AStream`，返回 `io.ReadCloser`，调用方自行解析 SSE。

## 计费

- **模型**：`speech-2.8-hd`（`type=audio`）
- **维度**：`audio`（按 `usage_characters` 字符数，默认单位 1 万字符）
- **任务**：每次调用创建 `audio` 类型任务

## 常见错误

| HTTP / 响应 | 原因 | 处理 |
|-------------|------|------|
| 401 | API Key 无效 | 检查 Bearer |
| 400 | `model` 缺失、模型未启用、余额不足 | 确认 `speech-2.8-hd` 已上架 |
| `base_resp.status_code != 0` | 上游 MiniMax 错误 | 看 `status_msg`、音色 ID 是否有效 |
| 400 | `subtitle_type=word_streaming` 且 `stream=false` | 改为 `stream: true` 或换 `sentence` |

## 混剪接入流程（参考）

1. 用户提交口播文案 → **POST `/v1/t2a_v2`**（`subtitle_enable: true`）  
2. 解码 `data.audio` → 上传 OSS / 加入时间线  
3. 拉取 `data.subtitle_file` → 生成字幕轨或给剪辑引擎  
4. （可选）成片或素材 wav 再走 [ASR 极速版](/api-asr-flash-doubao) 校对时间轴  

## 参考

- [MiniMax 官方 · 同步语音合成 T2A](https://platform.minimaxi.com/document/T2A%20V2)
- [录音文件 ASR（极速版）](/api-asr-flash-doubao)

</div>