MaaS HL SPeech

一、T2A v2（同步语音生成）

url

https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/t2a_v2

请求方式

post

content-type

application/json

入参

字段名	类型	是否必填	描述
text	string	是	待合成的文本，长度限制<10000字符，段落切换用换行符替代。（如需要控制语音中间隔时间，在字间增加<#x#>,x单位为秒，支持0.01-99.99，最多两位小数）。支持自定义文本与文本之间的语音时间间隔，以实现自定义文本语音停顿时间的效果。需要注意的是文本间隔时间需设置在两个可以语音发音的文本之间，且不能设置多个连续的时间间隔。
voice_setting	object	否	控制生成声音的语速、音量、语调等参数。
audio_setting	object	否	控制生成声音的采样率、比特率和音频格式。
pronunciation_dict	object	否	控制音色混合的参数，与voice_id二选一必填。
timber_weights	array	否	权重，须与voice_id同步填写，最多支持4种音色混合，取值范围[1,100]。
stream	bool	否	是否流式。默认false，即不开启流式。
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', 'auto'
subtitle_enable	bool	否	控制是否开启字幕服务的开关。默认为false。
output_format	string	否	控制输出结果形式的参数。可选值为urlhex。默认值为hex。该参数仅在非流式场景生效，流式场景仅支持返回hex形式。

voice_setting参数

字段名	类型	是否必填	说明
speed	Float	否	语速范围[0.5,2]，默认值为1.0，取值越大语速越快。
vol	Float	否	音量范围(0,10]，默认值为1.0，取值越大音量越高。
pitch	int	否	语调范围[-12,12]，默认值为0，0表示原音色输出，取值需为整数。
voice_id	string	是	请求的音色编号。与timber_weights二选一“必填”。 支持系统音色(id)以及复刻音色（id）两种类型，其中系统音色（ID）如下 青涩青年音色：male-qn-qingse 精英青年音色：male-qn-jingying 霸道青年音色：male-qn-badao 青年大学生音色：male-qn-daxuesheng 少女音色：female-shaonv 御姐音色：female-yujie 成熟女性音色：female-chengshu 甜美女性音色：female-tianmei 男性主持人：presenter_male 女性主持人：presenter_female 男性有声书1：audiobook_male_1 男性有声书2：audiobook_male_2 女性有声书1：audiobook_female_1 女性有声书2：audiobook_female_2 青涩青年音色-beta：male-qn-qingse-jingpin 精英青年音色-beta：male-qn-jingying-jingpin 霸道青年音色-beta：male-qn-badao-jingpin 青年大学生音色-beta：male-qn-daxuesheng-jingpin 少女音色-beta：female-shaonv-jingpin 御姐音色-beta：female-yujie-jingpin 成熟女性音色-beta：female-chengshu-jingpin 甜美女性音色-beta：female-tianmei-jingpin 聪明男童：clever_boy 可爱男童：cute_boy 萌萌女童：lovely_girl 卡通猪小琪：cartoon_pig 病娇弟弟：bingjiao_didi 俊朗男友：junlang_nanyou 纯真学弟：chunzhen_xuedi 冷淡学长：lengdan_xiongzhang 霸道少爷：badao_shaoye 甜心小玲：tianxin_xiaoling 俏皮萌妹：qiaopi_mengmei 妩媚御姐：wumei_yujie 嗲嗲学妹：diadia_xuemei 淡雅学姐：danya_xuejieSanta Claus：Santa_Claus Grinch：Grinch Rudolph：Rudolph Arnold：Arnold Charming Santa：Charming_Santa Charming Lady：Charming_Lady Sweet Girl：Sweet_Girl Cute Elf：Cute_Elf Attractive Girl：Attractive_Girl Serene Woman：Serene_Woman
emotion	string	否	控制合成语音的情绪；当前支持7种情绪：高兴，悲伤，愤怒，害怕，厌恶，惊讶，中性；参数范围["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]
latex_read	bool	否	控制是否支持朗读latex公式，默认为false。需注意：1. 请求中的公式需要在公式的首尾加上\$$；2. 请求中公式若有"\"，需转义成"\\"。示例：导数的基本公式是\$$\\frac{d}{dx}(x^n) = nx^{n-1}\$$
english_normalization	bool	否	该参数支持英语文本规范化，可提升数字阅读场景的性能，但会略微增加延迟。如果未提供，则默认值为 false。

audio_setting参数

字段名	类型	是否必填	说明
sample_rate	int	否	采样率范围[8000,16000,22050,24000,32000,44100]，默认值为32000。
bitrate	int	否	比特率范围[32000,64000,128000,256000]，默认值为128000，仅对mp3格式音频有效。
format	string	否	生成的音频格式，默认值为mp3，可选范围[mp3,pcm,flac,wav]。
channel	int	否	声道数，默认值为1（单声道），可选值为1（单声道）或2（双声道）。

pronunciation_dict参数

字段名	类型	是否必填	说明
tone	list\	否	替换需要特殊标注的文字、符号及对应的注音。替换发音（调整声调/替换其他字符发音）。 格式如下：["燕少飞/(yan4)(shao3)(fei1)","达菲/(da2)(fei1)"，"omg/oh my god"]声调用数字代替，一声（阴平）为1，二声（阳平）为2，三声（上声）为3，四声（去声）为4），轻声为5。

timber_weights参数

字段名	类型	是否必填	说明
voice_id	string	否	请求的音色id。须和weight参数同步填写。
weight	int	否	范围[1,100]权重，须与voice_id同步填写。最多支持4种音色混合，取值为整数，单一音色取值占比越高，合成音色越像。

出参

字段名	参数类型	说明
data	object	返回的数据对象，可能为 null，需要进行非空判断。
trace_id	string	本次会话的 ID，用于在咨询/反馈时帮助定位问题。
extra_info	object	相关额外信息。
base_resp	object	如果请求出错，对应的错误状态码和详情。

data参数

字段名	类型	说明
audio	string	合成后的音频片段，采用 hex 编码，按照输入定义的格式生成（mp3/pcm/flac）。
subtitle_file	string	合成的字幕下载链接，音频文件对应的字幕，精确到句（不超过 50 字），单位为毫秒，格式为 JSON。
status	int	当前音频流状态，1 表示合成中，2 表示合成结束。

extra_info参数

字段名	类型	说明
audio_length	long	音频时长，精确到毫秒。
audio_sample_rate	long	采样率。
audio_size	long	音频大小，单位为字节。
bitrate	long	比特率。
audio_format	string	生成音频文件的格式，取值范围 mp3/pcm/flac。
audio_channel	long	生成音频声道数，1：单声道，2：双声道。
invisible_character_ratio	double	非法字符占比。非法字符不超过 10%（包含 10%），音频会正常生成并返回非法字符占比；最大不超过 0.1（10%），超过进行报错。
usage_characters	long	计费字符数，本次语音生成的计费字符数。

base_resp参数

字段名	类型	说明
status_code	int64	状态码。1000：未知错误；1001：超时；1002：触发限流；1004：鉴权失败；1039：触发 TPM 限流；1042：非法字符超过 10%；2013：输入格式信息不正常。
status_msg	string	状态详情。

curl

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/t2a_v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {KEY}' \
--data-raw '{
    "text": "真正的危险不是计算机开始像人一样思考，而是人开始像计算机一样思考。计算机只是可以帮我们处理一些简单事务。",
    "stream": false,
    "language_boost": "auto",
    "output_format": "url",
    "voice_setting": {
        "voice_id": "male-qn-qingse",
        "speed": 1,
        "vol": 1,
        "pitch": 0,
        "emotion": "happy"
    },
    "audio_setting": {
        "sample_rate": 32000,
        "bitrate": 128000,
        "format": "mp3"
    }
}'

二、T2A Large v2（异步超长文本语音生成）

1、文件上传

url

https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/file/upload

请求方式

post

content-type

form/data

入参

字段名	类型	是否必填	描述
purpose	string	是	文件使用目的。取值及支持格式如下：t2a_async_input：创建语音生成任务时使用到的文件，支持txt、zipt格式的文档；
file	file	是	文件

出参

字段名	类型	说明
file	object	文件信息对象，包含文件的详细信息。
base_resp	object	基础响应信息对象，包含状态码和状态消息。

file参数

字段名	类型	说明
file_id	int64	文件的唯一标识符。
bytes	int	文件大小，单位为字节。
created_at	int64	文件的创建时间，Unix 时间戳格式。
filename	string	文件名称。
purpose	string	文件的用途，当前为 t2a_async_input。

base_resp参数

字段名	类型	说明
status_code	int64	状态码，0 表示成功。
status_msg	string	状态消息，success 表示请求成功。

curl

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/file/upload' \
--header 'Authorization: Bearer {KEY}' \
--form 'purpose="t2a_async_input"' \
--form 'file=@"/C:/Users/xxx/Desktop/FJC/文档.txt"'

2、创建异步任务

url

https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/t2a_async_v2

请求方式

post

content-type

application/json

入参

字段名	类型	是否必填	描述
text	string	否	待合成的文本，限制最长5万字符。和"text_file_id"二选一必填。
text_file_id	long	否	文件上传接口返回的file_id。待合成的文本文件id，单txt长度限制<10万字符，格式支持txt、zip。和"text"二选一必填。传入后自动校验格式. 1.txt：长度限制<100000字符（如需要控制语音中间隔时间，在字间增加<#x#>,x单位为秒，支持0.01-99.99s，最多两位小数）支持自定义文本与文本之间的语音时间间隔，以实现自定义文本语音停顿时间的效果。需要注意的是文本间隔时间需设置在两个可以语音发音的文本之间，且不能设置多个连续的时间间隔; 2.zip：打包上传，包里应只包含txt或json文件（压缩包内为同一格式文件），json文件可以有三个字段，["title", "content", "extra"]，分别表示标题，正文，作者。最终会产出三份结果分别对应三个字段，一共9个文件在一个文件夹中。如果某字段不存在，或者内容为空，则不会生成相应文件。
voice_setting	object	否	控制生成声音的语速、音量、语调等参数。
audio_setting	object	否	控制生成声音的采样率、比特率和音频格式。
pronunciation_dict	object	否	控制音色混合的参数，与voice_id二选一必填。
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', 'auto'

voice_setting参数

字段名	类型	是否必填	说明
speed	Float	否	语速范围[0.5,2]，默认值为1.0，取值越大语速越快。
vol	Float	否	音量范围(0,10]，默认值为1.0，取值越大音量越高。
pitch	int	否	语调范围[-12,12]，默认值为0，0表示原音色输出，取值需为整数。
voice_id	string	是	请求的音色编号，支持系统音色(id)以及复刻音色（id）两种类型， 其中系统音色（ID）如下：青涩青年音色：male-qn-qingse 精英青年音色：male-qn-jingying 霸道青年音色：male-qn-badao 青年大学生音色：male-qn-daxuesheng 少女音色：female-shaonv 御姐音色：female-yujie 成熟女性音色：female-chengshu 甜美女性音色：female-tianmei 男性主持人：presenter_male 女性主持人：presenter_female 男性有声书1：audiobook_male_1 男性有声书2：audiobook_male_2 女性有声书1：audiobook_female_1 女性有声书2：audiobook_female_2 青涩青年音色-beta：male-qn-qingse-jingpin 精英青年音色-beta：male-qn-jingying-jingpin 霸道青年音色-beta：male-qn-badao-jingpin 青年大学生音色-beta：male-qn-daxuesheng-jingpin 少女音色-beta：female-shaonv-jingpin 御姐音色-beta：female-yujie-jingpin 成熟女性音色-beta：female-chengshu-jingpin 甜美女性音色-beta：female-tianmei-jingpin 聪明男童：clever_boy 可爱男童：cute_boy 萌萌女童：lovely_girl 卡通猪小琪：cartoon_pig
emotion	string	否	控制合成语音的情绪；当前支持7种情绪：高兴，悲伤，愤怒，害怕，厌恶，惊讶，中性；参数范围["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]
english_normalization	bool	否	该参数支持英语文本规范化，可提升数字阅读场景的性能，但会略微增加延迟。如果未提供，则默认值为 false。

audio_setting参数

字段名	类型	是否必填	说明
sample_rate	int	否	采样率范围[8000,16000,22050,24000,32000,44100]，默认值为32000。
bitrate	int	否	比特率范围[32000,64000,128000,256000]，默认值为128000，仅对mp3格式音频有效。
format	string	否	生成的音频格式，默认值为mp3，可选范围[mp3,pcm,flac,wav]。
channel	int	否	声道数，默认值为1（单声道），可选值为1（单声道）或2（双声道）。

pronunciation_dict参数

字段名	类型	是否必填	说明
tone	list\	否	替换需要特殊标注的文字、符号及对应的注音。替换发音（调整声调/替换其他字符发音） 格式如下：["燕少飞/(yan4)(shao3)(fei1)","达菲/(da2)(fei1)"，"omg/oh my god"]声调用数字代替，一声（阴平）为1，二声（阳平）为2，三声（上声）为3，四声（去声）为4），轻声为5。

出参

字段名	参数类型	说明
taskId	long	异步任务id

curl

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/t2a_async_v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {KEY}' \
--data-raw '{
    "text": "我爱中国",
    "language_boost": "auto",
    "voice_setting": {
        "voice_id": "audiobook_male_1",
        "speed": 1,
        "vol": 1,
        "pitch": 1
    },
    "pronunciation_dict": {
        "tone": [
            "草地/(cao3)(di1)"
        ]
    },
    "audio_setting": {
        "audio_sample_rate": 32000,
        "bitrate": 128000,
        "format": "mp3",
        "channel": 2
    }
}'

3、获取异步任务状态

url

https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/task/{taskId}

请求方式

get

入参

字段名	类型	是否必填	描述
taskId	string	是	创建异步任务接口返回的taskId

出参

字段名	类型	说明
taskId	string	任务的唯一标识符。
status	string	任务的状态，例如 SUCCESS、Fail、Processing、Preparing、Queueing。
fileId	string	文件的唯一标识符。

curl

curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/tts/task/1915360414669643778' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {KEY}'

4、文件下载

url

https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/files/retrieve?taskId=19153409980342...\&fileId=261877976...

请求方式

get

入参

字段名	类型	是否必填	描述
taskId	string	是	获取异步任务状态接口返回的taskId
fileId	string	是	获取异步任务状态接口返回的fileId

出参

字段名	类型	说明
fileId	string	文件的唯一标识符。
bytes	int	文件大小，单位为字节。
createdAt	int64	文件的创建时间，Unix 时间戳格式。
filename	string	文件名称，包含扩展名。
purpose	string	文件的用途，例如 t2a_async。
mediaUrl	string	文件的下载地址，包含访问权限签名的完整 URL。
expireTime	int64	文件的过期时间，Unix 时间戳格式，表示该文件的下载链接失效时间。

curl

curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/{endpoint}/hailuo/files/retrieve?taskId=1915340998034292737&fileId=261877976617219' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {KEY}'