# 同步语音合成

**方法**: `POST`
**路径**: `/minimax/v1/t2a_v2`

[官方文档](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http)

通过提交 post请求{{BASE\_URL}}/minimaxi/v1/voice\_design
并同步得到结果

## 请求参数

### Header 参数

```text
Content-Type
string
必需
示例:
<content-type>
Authorization
string
可选
默认值:
Bearer {{YOUR_API_KEY}}
```

### Body 参数 application/json 必填

```text
model
string
必需
请求的模型版本，可选范围：speech-2.6-hd, speech-2.6-turbo, speech-02-hd, speech-02-turbo, speech-01-hd, speech-01-turbo.
text
string
需要合成语音的文本
必需
stream
boolean
可选
控制是否流式输出。默认 false，即不开启流式
voice_setting
object
必需
voice_id
string
必需
speed
number
可选
合成音频的语速，取值越大，语速越快。取值范围 [0.5,2]，默认值为1.0
vol
number
可选
合成音频的音量，取值越大，音量越高。取值范围 (0,10]，默认值为 1.0
pitch
integer
可选
合成音频的语调，取值范围 [-12,12]，默认值为 0，其中 0 为原音色输出
emotion
string
可选
控制合成语音的情绪，参数范围 ["happy", "sad", "angry", "fearful", "disgusted", "surprised", "calm", "fluent"]，分别对应 8 种情绪：高兴，悲伤，愤怒，害怕，厌恶，惊讶，中性，生动
模型会根据输入文本自动匹配合适的情绪，一般无需手动指定
该参数仅对 speech-2.6-hd, speech-2.6-turbo, speech-02-hd, speech-02-turbo, speech-01-hd, speech-01-turbo 模型生效
选项 fluent 仅对 speech-2.6-turbo, speech-2.6-hd 模型生效
可用选项: happy, sad, angry, fearful, disgusted, surprised, calm, fluent
text_normalization
boolean
可选
是否启用中文、英语文本规范化，开启后可提升数字阅读场景的性能，但会略微增加延迟，默认值为 false
latex_read
boolean
可选
控制是否朗读 latex 公式，默认为 false
pronunciation_dict
object
可选
tone
array
[string]
可选
audio_setting
object
可选
sample_rate
integer
可选
生成音频的采样率。可选范围[8000，16000，22050，24000，32000，44100]，默认为 32000
bitrate
integer
可选
生成音频的比特率。可选范围[32000，64000，128000，256000]，默认值为 128000。该参数仅对 mp3 格式的音频生效
format
string
可选
生成音频的格式，wav 仅在非流式输出下支持
可用选项: mp3, pcm, flac, wav
channel
integer
可选
生成音频的声道数。可选范围：[1,2]，其中 1 为单声道，2 为双声道，默认值为 1
force_cbr
boolean
可选
对于音频恒定比特率（cbr）控制，可选 false、 true。当此参数设置为 true，将以恒定比特率方式进行音频编码。
注意：本参数仅当音频设置为流式输出，且音频格式为 mp3 时生效。
subtitle_enable
boolean
可选
stream_options
object
可选
exclude_aggregated_audio
string
必需
设置最后一个 chunk 是否包含拼接后的语音 hex 数据。默认值为 False，即最后一个 chunk 中包含拼接后的完整语音 hex 数据
timber_weights
object
可选
voice_id
string
必需
weight
integer
必需
合成音频各音色所占的权重，须与 voice_id 同步填写。可选值范围为[1, 100]，最多支持 4 种音色混合，单一音色取值占比越高，合成音色与该音色相似度越高.
language_boost
string
可选
是否增强对指定的小语种和方言的识别能力。默认值为 null，可设置为 auto 让模型自主判断。
可用选项: Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans, auto
voice_modify
object
可选
声音效果器设置，该参数支持的音频格式：
非流式：mp3, wav, flac
流式：mp3
pitch
integer
可选
音高调整（低沉/明亮），范围 [-100,100]，数值接近 -100，声音更低沉；接近 100，声音更明亮
intensity
integer
可选
强度调整（力量感/柔和），范围 [-100,100]，数值接近 -100，声音更刚劲；接近 100，声音更轻柔
timbre
integer
可选
音色调整（磁性/清脆），范围 [-100,100]，数值接近 -100，声音更浑厚；数值接近 100，声音更清脆
sound_effects
string
可选
音效设置，单次仅能选择一种，可选值：
spacious_echo（空旷回音）
auditorium_echo（礼堂广播）
lofi_telephone（电话失真）
robotic（电音）
可用选项: spacious_echo, auditorium_echo, lofi_telephone, robotic
subtitle_enable
boolean
可选
控制是否开启字幕服务，默认值为 false。此参数仅在非流式输出场景下有效，且仅对 speech-2.6-hd speech-2.6-turbo speech-02-turbo speech-02-hd speech-01-turbo speech-01-hd 模型有效
output_format
string
可选
控制输出结果形式的参数，可选值范围为[url, hex]，默认值为 hex 。该参数仅在非流式场景生效，流式场景仅支持返回 hex 形式。返回的 url 有效期为 24 小时
可用选项: url, hex
aigc_watermark
boolean
可选
控制在合成音频的末尾添加音频节奏标识，默认值为 False。该参数仅对非流式合成生效
示例
{
"model"
:
"speech-2.6-hd"
,
"text"
:
"今天是不是很开心呀，当然了！"
,
"stream"
:
false
,
"voice_setting"
:
{
"voice_id"
:
"male-qn-qingse"
,
"speed"
:
1
,
"vol"
:
1
,
"pitch"
:
0
,
"emotion"
:
"happy"
}
,
"pronunciation_dict"
:
{
"tone"
:
[
"处理/(chu3)(li3)"
,
"危险/dangerous"
]
}
,
"audio_setting"
:
{
"sample_rate"
:
32000
,
"bitrate"
:
128000
,
"format"
:
"mp3"
,
"channel"
:
1
}
,
"subtitle_enable"
:
false
}
```

## 请求示例代码

### Shell

```bash
curl --location --request POST '/minimax/v1/t2a_v2' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: <content-type>' \
--data-raw '{
  "model": "speech-2.6-hd",
  "text": "今天是不是很开心呀，当然了！",
  "stream": false,
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  },
  "pronunciation_dict": {
    "tone": [
      "处理/(chu3)(li3)",
      "危险/dangerous"
    ]
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  },
  "subtitle_enable": false
}'
```

## 返回响应

### 🟢 200 成功

**内容类型**: `application/json`

#### 响应结构

```text
data
object
可选
返回的合成数据对象，可能为 null，需进行非空判断
audio
string
可选
合成后的音频数据，采用 hex 编码，格式与请求中指定的输出格式一致
status
integer
可选
当前音频流状态：1 表示合成中，2 表示合成结束
subtitle_file
string
可选
合成的字幕下载链接。音频文件对应的字幕，精确到句（不超过 50 字），单位为毫秒，格式为 json
extra_info
object
可选
audio_length
integer
音频时长（毫秒）
可选
audio_sample_rate
integer
音频采样率
可选
audio_size
integer
可选
音频文件大小（字节）
bitrate
integer
音频比特率
可选
word_count
integer
可选
已发音的字数统计，包含汉字、数字、字母，不包含标点符号
invisible_character_ratio
integer
可选
非法字符占比.非法字符不超过 10%（包含 10%），音频会正常生成,并返回非法字符占比数据；如超过 10% 将进行报错
usage_characters
integer
计费字符数
可选
audio_format
string
可选
生成音频文件的格式。取值范围 [mp3, pcm, flac]
audio_channel
integer
可选
生成音频声道数,1：单声道，2：双声道
trace_id
string
可选
base_resp
object
可选
status_code
integer
必需
状态码。
0: 请求结果正常
1000: 未知错误
1001: 超时
1002: 触发限流
1004: 鉴权失败
1039: 触发 TPM 限流
1042: 非法字符超过 10%
2013: 输入参数信息不正常
status_msg
string
状态详情
必需
```

#### 示例

```json
{
    "data": {
        "audio": "<hex编码的audio>",
        "status": 2
    },
    "extra_info": {
        "audio_length": 9900,
        "audio_sample_rate": 32000,
        "audio_size": 160323,
        "bitrate": 128000,
        "word_count": 52,
        "invisible_character_ratio": 0,
        "usage_characters": 26,
        "audio_format": "mp3",
        "audio_channel": 1
    },
    "trace_id": "01b8bf9bb7433cc75c18eee6cfa8fe21",
    "base_resp": {
        "status_code": 0,
        "status_msg": "success"
    }
}
```