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

# 语音合成（TTS）

> 同步 t2a_v2、异步 t2a_async_v2 与查询

概述

* 同步：`POST /minimaxi/v1/t2a_v2`
* 异步：`POST /minimaxi/v1/t2a_async_v2` + `GET /minimaxi/v1/query/t2a_async_query_v2`

<Tabs>
  <Tab title="同步合成">
    ```bash theme={null}
    curl -X POST "$BASE_URL/minimaxi/v1/t2a_v2" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"model":"speech-2.8-hd","text":"欢迎使用 HingNet AI","output_format":"hex"}' \
      --output minimaxi-tts.mp3
    ```
  </Tab>

  <Tab title="异步合成与查询">
    ```bash theme={null}
    curl -X POST "$BASE_URL/minimaxi/v1/t2a_async_v2" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"model":"speech-2.8-hd","text":"hello"}'

    curl "$BASE_URL/minimaxi/v1/query/t2a_async_query_v2?task_id=$TASK_ID" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

## 音色别名与情感（voice alias）

* 为了与 OpenAI 风格保持一致，HingNet AI 为常见音色提供别名到 MiniMax 实际音色的映射：
  * `alloy` → `female-chengshu`（女声-成熟）
  * `echo` → `male-qn-qingse`（男声-青年-清色）
  * `fable` → `male-qn-jingying`（男声-青年-精英）
  * `onyx` → `presenter_male`
  * `nova` → `presenter_female`
  * `shimmer` → `audiobook_female_1`

* 如果你在请求体中填写 `voice_id` 为上述别名，HingNet AI 会自动转换为 MiniMax 要求的 `voice_id`；当该音色存在默认情感时，会在未显式指定 `emotion` 时自动补全。

自定义别名（渠道自定义参数示例）

```json theme={null}
{
  "voice": {
    "alloy": "female-chengshu|sad",
    "echo": "male-qn-qingse|happy"
  }
}
```

## 返回格式（audio\_mode）

* 通过渠道自定义参数可设置音频返回模式：
  * `audio_mode = json`（默认）：响应体以 JSON 返回，`data.audio` 为 hex 或 URL（由 `output_format` 决定）。
  * `audio_mode = hex`：当 `output_format=hex` 时返回裸音频流；当 `output_format=url` 时仍返回 JSON。

配置示例（渠道自定义参数）

```json theme={null}
{
  "audio_mode": "hex"
}
```

<Callout type="tip">
  异步合成任务（t2a\_async\_v2）在返回 JSON 载荷中会原样保留你的 `voice_id` 与参数；若你使用了别名，HingNet AI 会在上游请求前进行一次转换与情感补全。
</Callout>

## 关键参数对齐（官方）

* `output_format`: 仅非流式生效，取值 `hex`（默认）或 `url`。`url` 有效期以官方返回为准。
* `emotion`: `happy/sad/angry/fearful/disgusted/surprised/calm/fluent/whisper`
* `sound_effects`: `spacious_echo/auditorium_echo/lofi_telephone/robotic`