本文档详细介绍同步合成接口 /v1/t2a\_v2 的调用方法，包括接口地址、输入输出参数、请求示例、响应示例及注意事项，适用于需要快速实现文本转语音同步合成的开发场景，供开发人员参考使用。

1. 认证方式

所有接口调用均需通过 API Key 认证，需在请求头中携带 Authorization 字段，格式如下：

Authorization: Bearer <YOUR_API_KEY>

说明：将 \<YOUR\_API\_KEY\>替换为您实际的 API Key，即可完成身份认证，获取接口调用权限。

2. 接口基础信息

• 接口用途：实现文本到语音的同步合成，支持多种模型版本、音色配置、情绪控制及音频参数自定义，可根据需求选择流式/非流式输出。

• 接口地址：https://api\.modelverse\.cn/v1/t2a\_v2

• 请求方式：POST

• Content-Type：application/json

3. 输入参数

输入参数分为基础必选参数和可选配置参数，部分参数存在依赖关系，具体说明如下，未标注“必选”的均为可选参数。

3.1 基础必选参数

3.2 流式输出控制参数

3.3 声音设置参数（voice_setting）

3.4 音频设置参数（audio_setting）

3.5 声调设置参数（pronunciation_dict）

3.6 音色比重参数（timber_weights）

用于设置混合音色，最多支持4种音色混合，需与 voice_setting.voice_id 配合使用（voice_setting.voice_id 需设为空），voice_id 与 weight 需同步填写。

3.7 语言增强参数（language_boost）

3.8 声音效果器参数（voice_modify）

用于调整声音效果，支持的音频格式：非流式（mp3, wav, flac）、流式（mp3）。

3.9 其他可选参数

4. 请求示例

如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具，避免命令行调用出现兼容问题。

curl --location --globoff 'https://api.modelverse.cn/v1/t2a_v2' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "speech-2.8-hd",
  "text": "今天是不是很开心呀(laughs)，当然了！",
  "stream": false,
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  },
  "pronunciation_dict": {
    "tone": [
      "处理/(chu3)(li3)",
      "危险/dangerous"
    ]
  },
  "subtitle_enable": false
}'

5. 输出参数

接口返回结果包含合成数据、附加信息、会话标识及请求状态，具体参数说明如下：

6. 响应示例

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

7. 注意事项

• 文本限制：text 字段长度需小于10000字符，超过3000字符推荐使用流式输出；停顿标记需设置在两个可发音文本之间，不可连续使用。

• 模型兼容性：语气词标签仅支持 speech-2.8-hd、speech-2.8-turbo 模型；emotion 字段的 fluent、whisper 仅支持 speech-2.6-hd、speech-2.6-turbo 模型。

• 音色配置：混合音色需将 voice_setting.voice_id 设为空，同时配置 timber_weights 参数，最多支持4种音色混合，voice_id 与 weight 需同步填写。

• 音频格式：wav 格式仅支持非流式输出；force_cbr 参数仅在流式输出且音频格式为 mp3 时生效。

• latex 朗读：开启 latex_read 后，language_boost 会自动设为 Chinese，公式需用 $$ 包裹，且 "\" 需转义为 "\\"。

• 字幕服务：subtitle_enable 仅在非流式输出时有效，开启后会返回字幕下载链接。

• 输出格式：output_format 仅在非流式场景生效，流式场景仅支持 hex 格式；url 形式的音频链接有效期为24小时，需及时下载。

• 非法字符：当非法字符占比超过10%时，接口会报错（status_code=1042），需清理非法字符后重新请求。

• 音效设置：voice_modify.sound_effects 单次仅能选择一种音效，且需匹配对应的音频格式。