文本转语音接口
更新时间：2026-05-11
语音合成
服务概述
- 通过人工智能语音引擎，将文本内容转换为自然流畅的语音音频。
服务申请
语音合成 API 采用控制台项目接入模式。用户可前往ViiTor AI官网 (https://www.viitor.com/) 注册并开通服务，在控制台创建项目后可获得鉴权所需信息。
业务服务地址由项目网关提供；本文档示例基于当前业务网关：
https://video-translation.ilivedata.com
接入方式
参数规范
- 请求 URL：
https://video-translation.ilivedata.com/speechSynthesis/textToSpeech - 请求方法：
POST - Content-Type：
application/json - 返回结构：
{code, message, data}
HTTP请求头
| Header | 必填 | 类型 | 说明 |
|---|---|---|---|
Content-Type | 是 | String | application/json;charset=UTF-8 |
Accept | 是 | String | application/json;charset=UTF-8 |
Authorization | 是 | String | 登录态令牌（Bearer Token） |
X-User-Id | 是 | Long | 用户ID，服务端会覆盖 body 中 userId |
X-Channel | 否 | Integer | 渠道编码，不传或非法时按 0 处理 |
X-App-Source | 否 | String | 来源标识，仅在 X-Channel != 100 时会写入 |
说明：
- 服务端以 Header 中的
X-User-Id为准。
请求方法：POST
请求体
字段定义
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
sourceText | String | 是 | 待合成文本，最大 5000 字，超过会截断 |
targetLanguage | String | 否 | 目标语言，传入时需在支持语种列表内 |
voiceName | String | 条件必填 | 音色名称，与 timbreNumber 二选一至少传一个 |
common | Integer | 否 | 音色类型标记（公共/私有） |
speedFactor | Float | 否 | 语速，范围 [0.5, 2]，默认 1.0 |
volume | Float | 否 | 音量，范围 [-60, 20]，默认 0 |
emotion | Integer | 否 | 情感参数，范围 [0, 6]，默认 0 |
selectedEngine | Integer | 否 | 指定合成引擎 |
format | String | 否 | 输出格式，支持 pcm/wav/mp3，默认 wav |
参数规则
sourceText必填。targetLanguage传入时必须为系统支持语种。format非法值会回退为wav。
响应体
统一返回结构
| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 0 表示成功，非 0 表示失败 |
message | String | 返回信息 |
data | Object | 业务数据 |
成功时 data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
taskId | String | 任务ID |
targetAudioUrl | String | 合成音频URL |
sourceLanguage | String | 检测/识别出的源语言 |
targetLanguage | String | 目标语言 |
speeches | Array | 分段语音信息（如有） |
调用示例
请求示例（cURL）
curl -X POST "https://video-translation.ilivedata.com/speechSynthesis/textToSpeech" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-H "X-User-Id: 123456" \
-H "X-Channel: 100" \
-d '{
"sourceText": "你好，这是一个语音合成测试。",
"targetLanguage": "zh",
"voiceName": "clone",
"speedFactor": 1.0,
"volume": 0,
"emotion": 0,
"format": "mp3"
}'
成功响应示例
{
"code": 0,
"message": "OK",
"data": {
"userId": 123456,
"taskId": "ViiTor_AI_XXXXXXXXXXXXXXXXXXXXXXXX",
"targetAudioUrl": "https://cdn.example.com/tts/result.mp3",
"sourceLanguage": "zh-CN"
}
}
失败响应示例（参数错误）
{
"code": 2001,
"message": "Invalid Parameter",
"data": null
}
常见错误码
| 错误码 | 含义 | 典型原因 |
|---|---|---|
2000 | Missing Parameter | 缺少必填参数（如 sourceText） |
2001 | Invalid Parameter | 参数不合法（语速、音量、情感、语言或音色参数错误） |
10091 | insufficient points | 用户积分不足 |
2107 | voice synthesis failed | 语音合成内部失败 |
客户端接入建议
- 先做参数前置校验：
sourceText、voiceName、format。 - 对
code != 0做统一异常处理，重点处理参数错误与积分不足。
