非实时语音合成(算法编码:2202069)
协议类型:HTTPS
一、接入点
| 环境 |
地址 |
| 公网 |
https://api-maas.teleai.com.cn/aipaas/voice/v1/tts/offLineSynthesis |
- API Path :
/aipaas/voice/v1/tts/offLineSynthesis
- 请求方法 :
POST
- Content-Type :
application/json
二、鉴权
采用请求头携带鉴权信息:
2.1 标准鉴权
Authorization: <鉴权信息>
| 请求头 |
必填 |
说明 |
Content-Type |
否 |
内容类型,固定 application/json |
X-APP-ID |
否 |
取值为控制台 → 应用及API Key → 创建应用 → AppID |
Device-Uuid |
否 |
设备uuid |
Authorization |
是 |
鉴权信息 |
2.2 Bearer Token 鉴权
Authorization: Bearer <用户申请的API-KEY>
| 请求头 |
必填 |
说明 |
Content-Type |
否 |
内容类型,固定 application/json |
Device-Uuid |
否 |
设备uuid |
Authorization |
是 |
Bearer <API_KEY> |
三、能力简介
- 离线语音合成,用于将待合成的文本转换为音频的场景。开发者需要保证在语音合成结果返回之前连接不中断;
- 支持输出格式:PCM,WAV,MP3 编码;
- 支持 8000 Hz,16000 Hz 采样率;
- 支持设置语速,音量;
- 支持设置多种说话人;
- 支持一次性合成 5000 字符以内的文字,其中 1 个汉字、1 个英文字母、1 个标点或 1 个句子中间空格均算作 1 个字符,超过 5000 个字符的内容将会截断;
- 仅支持采用 UTF-8 编码的文本输入;
3.1 修订历史
| 修订日期 |
算法版本号 |
修订内容 |
| 2025-12-19 |
V1.2.1 |
修复英文单词读法 |
| 2025-12-19 |
V1.2.0 |
接入天眼 bug |
四、请求与响应
4.1 请求参数
| 参数名 |
必填 |
类型 |
说明 |
req_id |
是 |
[string] |
请求全局唯一 ID,记录该值便于排查问题,不可为空字符串 |
text |
是 |
[string] |
待合成的文本,需要为 UTF-8 编码,不可为空字符串 |
ret_mode |
否 |
[int] |
合成音频的返回模式:1:音频数据流(包括元数据),默认值;2:音频 URL(包括元数据 URL) |
format |
否 |
[string] |
音频编码格式,支持 PCM、WAV、MP3 格式,默认值:PCM |
voice |
否 |
[string] |
说话人,默认值:yixiaoling, 可支持 yixiaoling、yixiaotian、yixiaoluo、yixiaotong、yixiaohui、yixiaoxuan、yixiaochao、yixiaowei、 yixiaoliang、yixiaoshen、yixiaojing、yixiaoke、yixiaorou、yixiaobei、yixiaoxin-female、yixiaoxin-male、yixiaobin、malili、tianxu、yixiaoqing、yixiaoyao、yixiaoni、yixiaoting、yixiaoqi、yixiaoqiong、yixiaolin、yixiaomeng、yixiaohan、yixiaoze、yixiaohong、yixiaowan、yixiaotang、yixiaoping、yixiaoyan、yixiaolan、yixiaotao、yixiaojun、yixiaolu、yixiaohao、sarah、morgan、molly、clara、elena、helen。其中sarah、morgan、molly、clara、elena、helen 为纯英文音色,不能说中文 |
sample_rate |
否 |
[int] |
音频采样率,支持 16000 Hz 和 8000 Hz,默认值:16000 |
volume |
否 |
[int] |
音量,取值范围:[0, 100],默认值:50 |
speech_rate |
否 |
[float] |
语速,取值范围:[0.5, 2.0],默认值:1.0 |
pitch |
否 |
[float] |
语调,取值范围:[0.5, 2.0],默认值:1.0 |
4.2 REST 参数
| 参数名 |
必填 |
类型 |
说明 |
code |
是 |
[string] |
算法编码 |
4.3 响应内容
4.3.1 顶层字段
| 参数名 |
必填 |
类型 |
说明 |
status |
否 |
[int] |
状态码,见服务码说明 (该字段即将下线) |
status_msg |
否 |
[string] |
状态说明,见服务码说明 (该字段即将下线) |
code |
否 |
[int] |
状态码,见服务码说明 |
message |
否 |
[string] |
状态说明,见服务码说明 |
result |
否 |
[object] |
合成结果 |
num_characters |
否 |
[int] |
字数统计 |
4.3.2 合成结果 result
| 参数名 |
必填 |
类型 |
说明 |
result>>audio |
否 |
[string] |
合成音频数据,经过 base64 编码 |
result>>audio_len |
否 |
[int] |
合成音频长度,单位:ms |
result>>phn_seq_len |
否 |
[int] |
合成音频音素序列长度 |
result>>phn_dur_seq |
否 |
[array] |
合成音频音素持续时间序列 |
result>>phn_name_seq |
否 |
[array] |
合成音频音素名称序列 |
result>>phn_id_seq |
否 |
[array] |
合成音频音素 ID 序列 |
4.4 成功响应示例(Mock API)
{
"status": 10000,
"status_msg": "Success",
"result": {
"audio": "//6YYmNiDlSUXjZlDP8yADQAQ1E2ANKJOaTqFGUgIwDQAKAA==",
"audio_len": 2500,
"phn_seq_len": 10,
"phn_id_seq": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
"phn_name_seq": ["j", "in1", "t", "ian1", "z", "en3", "m", "e1", "l", "e5"],
"phn_dur_seq": [150, 350, 150, 350, 150, 350, 150, 350, 150, 350]
}
}
五、状态码说明
5.1 算法状态码
通用状态码请参考【状态码】中的【网关认证】,其余状态码如下:
| 返回码 |
解释 |
说明 |
解决方法 |
10301 |
Required parameter miss |
必填参数缺失 |
检查请求体是否符合接口协议 |
10302 |
Too many requests |
并发请求过多 |
联系商务,增加并发 |
10304 |
Parse request body fail |
请求格式错误 |
查看请求的 URL body 格式是否正确,参考接口文档 |
10401 |
Authorize fail |
授权失败 |
联系技术人员 |
10503 |
Server connection time out |
服务连接超时 |
联系技术人员 |
10903 |
Recognize failed |
识别失败 |
联系技术人员 |
10000 |
Success |
成功 |
执行下一步操作 |
5.2 公共状态码
- 接口响应的公共状态码由网关统一定义,一般用于标识鉴权失败、限流或服务异常,具体业务错误码、错误信息及排查建议请参考:开发指南-公共信息及状态码。
六、调用示例
6.1 请求参数示例
{
"req_id": "test001",
"text": "今天是周一,天气挺好的。"
}
七、代码调用示例
7.1 Java(JDK 1.8)
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONUtil;
import java.util.HashMap;
import java.util.Map;
/** 主类,用于发起HTTP请求并处理响应 */
public class Example {
public static void main(String[] args) {
example();
}
/**
* 方法中使用到的 JSONUtil、HttpRequest、HttpResponse均来自Hutool工具类。
* 具体maven依赖为:
*
* cn.hutool
* hutool-all
* 5.8.29
*
*/
public static void example() {
try {
String url = "算法调用地址";
// 设置请求头
Map headers = new HashMap();
//公网调用鉴权
headers.put("X-APP-ID", "yourAppId");
headers.put("Authorization", "yourAuthorization");
// 创建请求对象
Map request = new HashMap();
request.put("req_id", "test001");
request.put("text", "今天是周一,天气挺好的。");
// 将请求对象转换为JsonNode
String requestString = JSONUtil.toJsonStr(request);
// 发起HTTP请求
HttpResponse response =
HttpRequest.post(url)
.headerMap(headers, true)
.body(requestString)
.execute();
// 输出响应结果
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
7.2 Python(Python 3.8)
import time
import requests
import warnings
from datetime import datetime
import logging
# 配置日志,设置日志级别为INFO,并指定日志格式
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
# 配置环境变量
# 公网调用鉴权
X_APP_ID = "yourAppId"
AUTHORIZATION = "yourAuthorization"
# URL 和请求数据
url = "算法调用地址" # 请求的URL
request_data = {
"req_id": "test001",
"text": "今天是周一,天气挺好的。"
}
# 构建请求头
headers = {
"Content-Type": "application/json",
# 公网调用鉴权,必传
"X-APP-ID": X_APP_ID,
"Authorization": AUTHORIZATION
}
# 忽略未验证的HTTPS请求警告
warnings.filterwarnings("ignore", message="Unverified HTTPS request")
def timeSimple(timestamp):
# 将时间戳转换为HH:MM:SS格式的时间字符串
dt_object = datetime.fromtimestamp(timestamp)
formatted_time = dt_object.strftime("%H:%M:%S")
return formatted_time
def send_request(url):
try:
start_time = time.time()
logging.info(f"请求路径: {url}")
logging.info(f"开始发送: {timeSimple(start_time)}")
with requests.post(
url, json=request_data, headers=headers, stream=True, verify=False
) as response:
first_packet_time = None
if response.status_code == 200:
logging.info(f"接受到返回: {timeSimple(time.time())}")
for chunk in response.iter_content(chunk_size=1024):
if chunk:
if first_packet_time is None:
first_packet_time = time.time()
logging.info(
f"Received chunk: {timeSimple(time.time())} {chunk.decode('utf-8')}"
)
end_time = time.time()
logging.info(f"Time to first byte (TTFB): {first_packet_time - start_time:.3f} seconds")
logging.info(f"Request completed in {end_time - start_time:.3f} seconds")
else:
logging.error(f"Request failed with status code {response.status_code}")
except Exception as e:
logging.error(f"An error occurred: {e}")
# 发送请求
send_request(url)
logging.info(f"headers = {headers}")