文档

SubmitTextTo3DAvatarVideoTask - 提交3D文本合成视频任务

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

提交根据一段文本离线生成3D数字人视频任务,该接口会立即返回一个TaskUuid作为本次提交任务的唯一id,后续可以根据TaskUuid调用查询和取消任务接口。

接口说明

提交根据一段文本离线生成 3D 数字人视频任务,该接口会立即返回一个 TaskUuid 作为本次提交任务的唯一 id,后续可以根据 TaskUuid 调用查询视频合成任务详情接口查询对应的任务的状态,当任务状态为已完成时可以获取到对应视频的下载地址,进行视频下载。在任务状态为未开始情况下,也可以通过 TaskUuid 调用取消视频合成任务接口,取消该任务。

说明 参考 3D 数字人视频合成使用指南了解完整的 3D 视频合成接入流程。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
avatar:SubmitTextTo3DAvatarVideoTaskWrite
  • 全部资源
    acs:avatar::{#accountId}:*

请求参数

名称类型必填描述示例值
TenantIdlong

租户 ID,从虚拟数字人开放平台中获取的 TenantId

xxxx
Appobject

App 信息,代表一个业务配置

AppIdstring

App ID。在开发者中心-实例管理页面获取对应的 appId,参考文档

3d95xx946a
Titlestring

提交的视频合成的任务标题,最长不超过 64 个字符

这是一个示例标题
Textstring

合成文本,最长不超过 1000 个字符。支持 SSML 指定 TTS 的多音字发音、停顿、特殊读法、数字人动作等,可参考: 3D 数字人视频合成使用指南

这是一个示例文本
VideoInfoobject

视频格式

IsAlphaboolean

是否需要透明通道, 默认 false

  • true: 开启透明通道,视频格式可通过 AlphaFormat 指定,支持 webm、mov、mp4
  • false:不开启透明通道,视频格式为 mp4
false
AlphaFormatinteger

透明通道格式 ,默认值 1

  • 1:webm
  • 2:mov
  • 3:mp4

注意 当 isAlpha 为 false 时,该字段忽略。mov 格式的透明视频文件大小会非常大,不推荐使用,建议使用 webm 或者 mp4。

1
IsSubtitlesboolean

是否需要字幕,默认值:true

  • true: 生成字幕,字幕文件格式为 ass 文件,会作为独立文件提供下载链接进行下载
  • false:不生成字幕

警告 该字段已废弃,传入 true 和 false 都会生成单独字幕文件,新增 SubtitleEmbedded 字段可控制是否将字幕合并到视频中。

true
SubtitleEmbeddedboolean

是否将字幕合并到视频中,默认值:false

  • true:字幕合并到视频中
  • false:字幕不合并到视频中
false
Resolutioninteger

生成的视频分辨率,目前支持:

  • 1:720 * 1280(竖屏)
  • 2:1280 * 720(横屏)
  • 3:1080 * 1920(竖屏)
  • 4:1920 * 1080(横屏)
1
BackgroundImageUrlstring

有效可访问的 url 背景图片地址,背景图片的分辨率必须要与生成的视频分辨率保持一致

  • 目前支持 jpg,jpeg,png 的图片格式
可访问的公网url地址
SubtitleStyleobject

字幕样式。

Namestring

字体名称,默认值:alibabapuhuiti

alibabapuhuiti
Colorstring

字体颜色,十六进制颜色码 RGBA。

#000000FF
OutlineColorstring

描边颜色,十六进制颜色码 RGBA。

#FFFFFF00
Yinteger

字幕 y 轴位置,画面顶端坐标为 0。默认值,1920x1080:984,1080x1920:1824。

984
Sizeinteger

字体大小,最小值:36,最大值:72,默认值:36。

36
AvatarInfoobject

数字人相关配置

Locateinteger

数字人机位

  • 0: 全身近景机位,默认机位
  • 1: 头部近景机位
  • 2: 全身远景机位
  • 3: 半身近景机位
  • 4: 半身远景机位
  • 5: 左边近景机位
  • 6: 右边近景机位

具体每个机位的效果预览可以参考: 3D 数字人视频合成使用指南

0
Angleinteger

数字人角度

  • 0: 正面,默认角度
  • 1: 左侧 30 度
  • 2: 右侧 30 度

具体每个角度的效果预览可以参考: 3D 数字人视频合成使用指南

0
Codestring

人物 code

CH_xxxxxxx
IndustryCodestring

行业 code,默认值:default

  • default - 默认通用
  • kefu - 客服行业
  • live - 直播场景
default
AudioInfoobject

音频相关配置,不传则使用资产中配置的默认值。

说明 部分阿里云语音合成的音色没有经过效果验证,可能会出现效果上的差异
Voicestring

TTS 播报发音人 code,从虚拟数字人开放平台-3D 资产管理页面获取,不传则使用资产中配置的发音人。

guijie
SpeechRateinteger

TTS 播报声音语速,取值范围:-500~500,不传则使用资产中配置的默认值。

[-500, 0, 500] 对应的语速倍速区间为 [0.5, 1.0, 2.0]。

-500 表示基准语速的 0.5 倍速; 0 表示基准语速的 1 倍速。1 倍速是指模型默认输出的合成语速,语速会依据每一个发音人略有不同,大概每秒钟 4 个字左右; 500 表示基准语速的 2 倍速;

计算方法如下:

0.8 倍速(1-1/0.8)/0.002 = -125

1.2 倍速(1-1/1.2)/0.001 = 166

0
Volumeinteger

TTS 播报声音音量,取值范围:0~100,不传则使用资产中配置的默认值。

0
PitchRateinteger

TTS 播报声音语调,取值范围:-500~500,不传则使用资产中配置的默认值。

0
SampleRateinteger

输出音频采样率(单位: Hz)。

枚举值:
  • 1600016000
  • 2400024000
  • 4800048000
16000
Callbackboolean

本次视频合成任务是否需要事件回调,默认 false 不回调。平台支持在任务开始和任务结束时进行事件回调,具体可参考文档:数字人回调事件通知

false
CallbackParamsstring

回调时需要透传的一些参数,json 格式字符串,callback=false 时不生效。

{ "xxx": "xxx" }
ExtParamsstring

一些扩展参数。

{"xxx": "xxx"}

返回参数

名称类型描述示例值
object

Schema of Response

RequestIdstring

请求 ID

13E0445E-CA7F-5DD3-9B0F-D4B39E0180F7
Successboolean

是否调用成功

false
Codestring

错误码

502
Messagestring

错误消息

这是一个错误
Dataobject

调用返回数据

TaskUuidstring

任务唯一 uuid,后续用来查询任务详情,请务必保存好

xxxxxx-xxxxx-xxxxx

TaskUuid 是该任务的唯一标识,请务必保存好。

示例

正常返回示例

JSON格式

{
  "RequestId": "13E0445E-CA7F-5DD3-9B0F-D4B39E0180F7",
  "Success": false,
  "Code": "502",
  "Message": "这是一个错误",
  "Data": {
    "TaskUuid": "xxxxxx-xxxxx-xxxxx"
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2024-01-08API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2024-01-08API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-07-05OpenAPI 入参发生变更看变更集
变更项变更内容
入参OpenAPI 入参发生变更
    新增入参:AudioInfo
    新增入参:Callback
    新增入参:CallbackParams
    新增入参:ExtParams
2022-08-18API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用