> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phanedge.cloud/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 "https://models.phanedge.cloud/minimaxi/v1/t2a_v2" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"model":"speech-2.8-hd","text":"欢迎使用 PhanEdge","output_format":"hex"}' \
      --output minimaxi-tts.mp3
    ```
  </Tab>

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

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

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

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

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

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

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

## 返回格式（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` 与参数；若你使用了别名，PhanEdge 会在上游请求前进行一次转换与情感补全。
</Callout>

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

* `output_format`: 仅非流式生效，取值 `hex`（默认）或 `url`。`url` 有效期以官方返回为准。
* `emotion`: `happy/sad/angry/fearful/disgusted/surprised/calm/fluent/whisper`。该能力受模型与音色组合限制，并非所有 `voice_id` 都支持；例如 `speech-2.6-hd` + `male-qn-qingse` 不建议配置默认 `happy`。
* `sound_effects`: `spacious_echo/auditorium_echo/lofi_telephone/robotic`


## OpenAPI

````yaml POST /minimaxi/v1/t2a_v2
openapi: 3.0.3
info:
  title: PhanEdge Core API
  version: '1.0'
  description: >-
    Core OpenAI-compatible and model-family endpoints used by the PhanEdge user
    docs.
servers:
  - url: https://models.phanedge.cloud
security:
  - BearerAuth: []
paths:
  /minimaxi/v1/t2a_v2:
    post:
      tags:
        - MiniMaxi
      summary: MiniMaxi text-to-speech
      requestBody:
        $ref: '#/components/requestBodies/JsonObject'
      responses:
        '200':
          $ref: '#/components/responses/JsonObject'
components:
  requestBodies:
    JsonObject:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericObject'
  responses:
    JsonObject:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericObject'
  schemas:
    GenericObject:
      type: object
      additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <token>'

````