文档首页/ 数字内容生产线 MetaStudio/ API参考/ 语音合成/ 语音合成异步任务管理/ 创建TTS异步任务
更新时间：2025-08-26 GMT+08:00
在线调试
CLI示例
查看PDF
分享

创建TTS异步任务

功能介绍

该接口用于对外生成音频文件。

使用本接口前，需要在MetaStudio控制台服务概览页面，开通“声音合成”的按需计费。

详细操作为：单击“声音合成”卡片中的“去开通”，在弹出的“开通按需计费服务提示”对话框中，勾选同意协议。单击“确定”，开通按需计费。

如需使用第三方声音进行语音合成，请购买出门问问声音套餐，操作请参考《用户指南》的“购买出门问问声音套餐”章节。

调用方法

请参见如何调用API。

URI

POST /v1/{project_id}/ttsc/async-jobs

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，获取方法请参考获取项目ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

用户Token。使用Token鉴权方式时必选。

通过调用IAM服务获取用户Token接口获取。

响应消息头中X-Subject-Token的值。

Authorization

否

String

使用AK/SK方式认证时必选，携带的鉴权信息。

X-Sdk-Date

否

String

使用AK/SK方式认证时必选，请求的发生时间。

X-Project-Id

否

String

使用AK/SK方式认证时必选，携带项目ID信息。

X-App-UserId

否

String

第三方用户ID。不允许输入中文。
表3 请求Body参数

参数

是否必选

参数类型

描述

text

是

String

待合成文本

tts_text

否

String

发送给tts的待合成文本

voice_asset_id

是

String

音色ID，获取方式详见获取音色ID。

speed

否

Integer

语速。

  • 当取值为“100”时，表示一个成年人正常的语速，约为250字/分钟。

  • 50表示0.5倍语速，100表示正常语速，200表示2倍语速。

取值范围：

50-200

默认取值：

100

pitch

否

Integer

音高。

取值范围：

50-200

默认取值：

100

volume

否

Integer

音量。

取值范围：

90-240

默认取值：

140

audio_format

否

String

输出音频文件格式。默认WAV。

  • WAV：wav格式。

  • MP3：mp3格式。

默认取值：

WAV

need_timestamp

否

Boolean

是否需要时间戳。false为不需要，true为需要返回时间戳信息。默认值为false。

默认取值：

false

silence_flag

否

Boolean

异常时是否返回静默音频流

默认取值：

false

silence_time_ms

否

Integer

异常时返回的静默音频流时长，单位毫秒。

取值范围：

0-5000

默认取值：

2000

callback_config

否

TtsCallBackConfig object

回调设置。

gen_srt

否

Boolean

是否开启字幕

srt_len

否

Long

字幕最大长度限制

取值范围：

0-10000

srt_line_limit

否

Integer

字幕行数限制，默认为1

取值范围：

0-5000

默认取值：

1

slice_segments

否

Boolean

是否对文本进行分段

默认取值：

true

channels

否

Integer

声道。（单声道|双声道）

默认值1，最小值1，最大值2。

取值范围：

1-2

默认取值：

1

output_external_url

否

String

音频文件上传的外部URL

说明：

  • 需要先申请开通白名单， 才允许将音频等文件上传到外部URL。

srt_output_external_url

否

String

字幕文件上传的外部URL

说明：

  • 需要先申请开通白名单， 才允许将字幕等文件上传到外部URL。

action_output_external_url

否

String

动作信息文件上传的外部URL

说明：

  • 需要先申请开通白名单， 才允许将时间戳等文件上传到外部URL。

is_vocabulary_config_enable

否

Boolean

是否应用当前租户的读法配置

is_concurrent_resource

否

Boolean

是否使用包周期路数资源进行计费

priority

否

Integer

优先级（0-10），0为最高优先级，默认5

取值范围：

0-10

默认取值：

10
表4 TtsCallBackConfig

参数

是否必选

参数类型

描述

callback_url

是

String

回调URL。

回调请求body为json格式，带参数如下：

status: FINISHED或ERROR或者WAITING

job_id: 任务id

audio_file_download_url: 音频文件路径

subtitle_file_download_url: 字幕文件路径

audio_duration: 音频时长（秒）

响应参数

状态码：200

表5 响应Body参数

参数

参数类型

描述

job_id

String

任务ID。

状态码：400

表6 响应Body参数

参数

参数类型

描述

error_code

String

业务返回码

  • MSS.000000001 - 失败

  • MSS.000000002 - 内部错误

  • MSS.000000003 - 非法参数

  • MSS.000000004 - 非法访问，未鉴权或者鉴权失败

error_msg

String

返回描述

request_id

String

请求唯一标识

状态码：500

表7 响应Body参数

参数

参数类型

描述

error_code

String

业务返回码

  • MSS.000000001 - 失败

  • MSS.000000002 - 内部错误

  • MSS.000000003 - 非法参数

  • MSS.000000004 - 非法访问，未鉴权或者鉴权失败

error_msg

String

返回描述

request_id

String

请求唯一标识

请求示例

POST https://{endpoint}/v1/3f0924078d1b471c884a5383d4dec9fa/ttsc/async-jobs

{
  "text" : "大家好，我是小花",
  "voice_asset_id" : "c84054e7f29543048d585f61248c64c9"
}

响应示例

状态码：200

处理成功。

{
  "job_id" : "26f06524-4f75-4b3a-a853-b649a21aaf66"
}

状态码

状态码

描述

200

处理成功。

400

参数异常

500

服务端异常

错误码

请参见错误码。

父主题： 语音合成异步任务管理