语音模板即用户听到的音频内容,您在发送语音通知和语音验证码前,需要先创建语音模板,审核通过后即可发送语音任务。
注意事项
完整流程
下图展示了从准备到最终通过 API 发送语音的完整路径及各环节预计耗时。
第一步:完成账号与资质准备
第二步:创建语音模板
登录语音服务控制台,在左侧导航栏,选择语音消息。
根据您的业务需要,选择语音通知或语音验证码。
语音通知支持文本转语音模板和语音通知文件。
文本转语音模板:指模板的内容是文本,在播放时自动转化为语音。
语音通知文件:指预先录制好的音频文件(MP3或WAV格式),在接听后直接播放该文件。
语音验证码仅支持文本转语音模板。
在语音通知或语音验证码页面创建语音模板。
创建文本转语音模板
单击添加模板,根据页面提示填写模板内容。
参数名称
参数说明
外呼号码(外呼模式)
公共模式文本转语音模板和专属模式文本转语音模板不通用,文本转语音模板外呼模式必须与业务场景外呼模式匹配。具体差异请参见公共模式和专属模式的区别。
公共模式外呼:若您不额外购买语音号码,使用语音服务提供的公共号码池内号码随机外呼,您必须选择此选项以创建公共模式的文本转语音模板。
专属模式外呼:若您使用在语音服务控制台购买的真实号码外呼,或使用服务实例调度已绑定的真实号码外呼,您必须选择此选项以创建专属模式的文本转语音模板。
模板名称
模板名称用于标识并区分您申请的众多模板。模板名称不超过30个字符。
模板内容
模板内容必须遵守语音模板规范。
语言
选择模板语言。
中文
英文
语速控制
设置语速。
声音类型
选择声音类型。
女声
男声
说明英文语言下声音类型仅支持女声。
声音音色
请选择声音音色。您可选择语速和声音音色后,单击“试听”图标
,配置合适的音频输出效果。使用说明
申请说明是模板审核的参考信息之一,请详细描述您的业务的使用场景,并提供可以验证这些业务的网站链接、APP 名称等信息。信息完善的申请说明会提高模板的审核效率。若您的业务为内部管理后台且无公开的线上充值入口,建议同时提供以下材料:(1)在说明中解释具体业务场景(如"线下转账通知"或"内部虚拟额度变动提醒"),并附上带有实际变量替换内容的示例文本(例如:"您正在注册成为${product}用户,验证码${code},感谢您的支持!");(2)提供内部管理后台的业务内容截图(敏感信息可打码)作为辅助证明;(3)仅提供简单文字描述不足以通过审核,必须提供可验证的业务载体信息,如 APP 名称、小程序名称、公众号名称或对应链接。
单击确定。创建完成,等待审核。
创建语音通知文件
单击导入语音文件,选择外呼号码类型并导入语音文件,等待审核。
重要公共模式外呼模板和专属模式外呼模板不通用,请选择适合您业务场景的外呼模式。具体差异请参见公共模式和专属模式的区别。
语音文件需为 wav 或 mp3 格式且小于 5M。提交成功后预计 2 小时内完成审核,审核工作时间为周一至周日 9:00—23:00(法定节假日顺延)。
提交语音文件后,您可在语音通知 > 语音通知文件标签页的列表中,单击对应语音文件行的试听按钮,收听您上传的自定义语音文件内容,确认音频效果是否符合预期。试听功能仅适用于选择专属模式外呼类型的语音通知文件。
第三步:审核流程
语音模板预计在2小时内完成审核。审核工作时间:周一至周日9:00~23:00(法定节假日顺延)。语音模板审核由人工专员综合评估,非系统自动判定。
模板内容中涉及的链接、APP、小程序等业务信息,必须属于当前账号企业认证的业务范围。若模板内容涉及第三方公司(尤其是自然人独资等不支持开通语音业务的主体类型)的业务,将导致审核失败。即使更换账号主体,也需确保模板内容与当前认证企业的业务范围一致。
审核通过后,您可以在语音通知或语音验证码列表页获取模板ID。模板ID是调用语音接口的必填参数。
若审核状态为未通过,单击原因,查看未通过原因。
不支持修改审核状态为通过、审核中、未通过的模板。
第四步:API 集成与发送
模板审核通过后,您就可以在您的应用程序中调用 API 来发送语音了。
获取模板ID/语音ID
模板ID:在语音通知或语音验证码的模板列表中,找到已通过审核的模板,并复制其模板ID(API 参数中称为
TtsCode)。这是调用 API 的关键凭证。语音ID:在语音文件管理列表中,找到已通过审核的语音文件,并复制其语音ID(API 参数中称为
VoiceCode)。这是调用 API 的关键凭证。
选择 API 接口
支持公共模式模板和专属模式模板的外呼接口:
SingleCallByTts:向指定号码发送语音验证码或文本转语音类型的语音通知。
SingleCallByVoice:向指定号码发送语音通知文件类型的语音通知。
仅支持使用专属模式模板的外呼接口:
创建语音通话任务CreateCallTask:使用服务实例给多个被叫号码创建文本转语音任务、语音通知任务和语音验证码任务。
执行语音通话任务ExecuteCallTask:启动已创建的语音通话任务。
说明创建和执行语音通话任务也可通过控制台交互式界面完成,详情请参见通过控制台使用语音通知/语音验证码。
变量传参排查
调用SingleCallByTts等接口发送文本转语音通知时,API 中传入的变量数量必须与语音模板中定义的变量数量严格一致,否则会导致呼叫失败。若遇到呼叫失败,建议按以下步骤排查:
核对语音模板内容中定义的变量数量(格式为
${变量名}),与 API 调用时TtsParam参数中实际传入的变量数量是否一致。使用 OpenAPI Explorer 测试运行接口,直接传入实际参数验证 API 调用是否成功。
参考阿里云官方 SDK 示例工程代码,对照检查参数传入格式是否正确。
常见问题
语音模板是否支持跨账号迁移、批量导出或导入?
不支持。语音通知模板数据与账号绑定,不支持跨账号迁移、批量导出或导入。如需在新账号中使用相同模板,需在新账号的语音服务控制台重新创建模板,并等待审核通过后方可使用。
更换语音服务号码后是否需要重新审批 TTS 模板?
不需要。更换语音服务号码后,已通过审核的文本转语音(TTS)模板无需重新审批,原模板可继续正常使用。语音模板的有效性与使用的具体号码无关。
模板删除后无法恢复,请谨慎操作。