更新时间:2025-08-26 GMT+08:00

查询视频制作剧本详情

功能介绍

该接口用于查询视频制作剧本详情。

调用方法

请参见如何调用API

URI

GET /v1/{project_id}/digital-human-video-scripts/{script_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方法请参考获取项目ID

script_id

String

剧本ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

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

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

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

Authorization

String

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

X-Sdk-Date

String

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

格式为(YYYYMMDD'T'HHMMSS'Z')。

X-Project-Id

String

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

X-App-UserId

String

第三方用户ID。不允许输入中文。

响应参数

状态码:200

表3 响应Header参数

参数

参数类型

描述

X-Request-Id

String

请求ID。

表4 响应Body参数

参数

参数类型

描述

script_name

String

参数解释

剧本名称。

约束限制

不涉及。

取值范围

只能使用中英文字符,字符长度1-256位。

默认取值

不涉及。

script_description

String

参数解释

剧本描述。

约束限制

不涉及。

取值范围

字符长度0-1024位。

默认取值

不涉及。

view_mode

String

参数解释

横竖屏类型。

约束限制

不涉及。

取值范围

  • LANDSCAPE:横屏。

  • VERTICAL:竖屏。

默认取值:

LANDSCAPE

model_asset_id

String

参数解释

数字人模型资产ID。

约束限制

不涉及

取值范围

字符长度0-64位。

默认取值

不涉及

model_asset_type

String

参数解释

数字人模型类型。

约束限制

不涉及

取值范围

  • HUMAN_MODEL_2D:分身数字人

默认取值

不涉及

voice_config

VoiceConfig object

语音配置参数。

video_config

VideoConfig object

视频输出配置。

priv_data

String

参数解释

私有数据,用户填写,原样带回。

约束限制

不涉及

取值范围

字符长度0-8192位

默认取值

不涉及

background_music_config

BackgroundMusicConfig object

背景音乐配置

review_config

ReviewConfig object

内容审核配置

audio_files

ShootScriptAudioFiles object

用于语音驱动的音频文件上传URL列表。

action_config

ActionConfig object

动作编排配置

说明:
  • 只对分身数字人视频制作生效

shoot_scripts

Array of ShootScriptShowItem objects

拍摄脚本列表。

script_id

String

剧本ID。

create_time

String

创建时间,格式遵循:RFC 3339 如"2021-01-10T08:43:17Z"。

update_time

String

更新时间,格式遵循:RFC 3339 如"2021-01-10T08:43:17Z"。

script_cover_url

String

剧本封面下载url。

表5 VoiceConfig

参数

参数类型

描述

voice_asset_id

String

参数解释

音色资产ID,可以从资产库中查询。

音色ID的查询操作,详见查询预置音色ID

约束限制

不涉及。

取值范围

字符长度1-256位。

默认取值

不涉及。

speed

Integer

参数解释

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

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

约束限制

不涉及。

取值范围:

50-200

默认取值:

100

pitch

Integer

参数解释

音高。

约束限制

不涉及。

取值范围:

50-200

默认取值:

100

volume

Integer

参数解释

音量。

约束限制

不涉及。

取值范围:

90-240

默认取值:

140

表6 VideoConfig

参数

参数类型

描述

clip_mode

String

参数解释

输出视频的剪辑方式。

约束限制

不涉及。

取值范围

  • RESIZE:视频缩放。

  • CROP:视频裁剪。

默认取值:

RESIZE

codec

String

参数解释

视频编码格式及视频文件格式。

约束限制

仅分身数字人视频制作支持VP8和QTRLE编码。QTRLE编码时文本驱动字符数限制小于1500字,音频驱动音频长度小于5分钟。

QTRLE编码需要先申请开通白名单后才能使用

取值范围

  • H264:h264编码,输出mp4文件。

  • VP8:vp8编码,输出webm文件。

  • QTRLE:qtrle ,输出mov文件。

默认取值

H264

默认取值:

H264

bitrate

Integer

参数解释

输出平均码率。单位:kbps。

约束限制

  • 分身数字人视频制作采用质量优先,可能会超过设置的码率。

  • 分身数字人直播码率范围[1000, 8000]。

默认取值

不涉及

取值范围:

40-30000

width

Integer

参数解释

视频宽度。单位:像素。

约束限制

  • clip_mode=RESIZE时,当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率。4K分辨率视频需要分身数字人模型支持4K的情况下才能使用。

  • clip_mode=CROP,裁剪后视频,(dx,dy)为原点,保留视频像宽度为width。

  • 分身数字人直播和智能交互目前只支持1080x1920、1920x1080。

默认取值

不涉及

取值范围:

0-3840

height

Integer

参数解释

视频高度。

单位:像素。

约束限制

  • clip_mode=RESIZE时,当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率分辨率。

  • clip_mode=CROP,裁剪后视频,(dx,dy)为原点,保留视频像高度为height。

  • 分身数字人直播和智能交互目前只支持1080x1920、1920x1080。

默认取值

不涉及

取值范围:

0-3840

frame_rate

String

参数解释

帧率。单位:FPS。

约束限制

分身数字人视频固定25FPS。

默认取值:

25

is_subtitle_enable

Boolean

参数解释

输出的视频是否带字幕。

约束限制

分身数字人直播暂时不支持字幕。

取值范围

  • true: 打开字幕

  • false: 关闭字幕

默认取值:

false

subtitle_config

SubtitleConfig object

字幕配置。

dx

Integer

参数解释

裁剪视频左上角像素点横坐标。

说明:
以模特分辨率为画布大小,比如1920*1080分辨率的模特,dx最小值是0,最大值是1920。

约束限制

clip_mode= CROP时生效。

默认取值

不涉及

取值范围:

-1920-3840

dy

Integer

参数解释

裁剪视频左上角像素点纵坐标。

说明:
以模特分辨率为画布大小,比如1920*1080分辨率的模特,dy最小值是0,最大值是1080

约束限制

clip_mode= CROP时生效。

默认取值

不涉及

取值范围:

-1920-3840

is_enable_super_resolution

Boolean

参数解释

视频是否开启超分。

约束限制

仅分身数字人视频制作支持。

取值范围

  • true: 开启

  • false: 不开启

默认取值:

false

is_end_at_first_frame

Boolean

参数解释

视频结束帧是否跟起始帧相同。需要多个数字人视频无缝拼接时设置成true。

约束限制

仅分身数字人视频制作支持,当视频制作时插入动作标签后此设置将失效。

取值范围

  • true: 开启

  • false: 不开启

默认取值:

false

output_external_url

String

视频文件上传的外部URL。

说明:
  • 需要先申请开通白名单后,才允许将视频上传到外部URL。

is_vocabulary_config_enable

Boolean

参数解释

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

约束限制

仅分身数字人视频制作支持。

取值范围

  • true: 开启

  • false: 不开启

默认取值:

true

表7 SubtitleConfig

参数

参数类型

描述

dx

Integer

参数解释

字幕框左下角像素点坐标。

约束限制

不涉及。

默认取值

不涉及。

取值范围:

0-1920

dy

Integer

参数解释

字幕框左下角像素点坐标。

约束限制

不涉及。

默认取值

不涉及。

取值范围:

0-1920

h

Integer

参数解释

字幕框高度。

约束限制

参数h用于方便前端计算字幕框左上角坐标,后台不使用该参数。

取值范围:

0-1920

w

Integer

参数解释

字幕框宽度。

约束限制

  • 字幕框宽度固定为屏幕宽度的80%

  • 参数w用于方便前端计算字幕框左上角坐标,后台不使用该参数

取值范围:

0-1920

font_name

String

参数解释

字体。当前支持的字体请参考服务支持的字体

约束限制

不涉及。

取值范围

字符长度0-64位

默认取值:

HarmonyOS_Sans_SC_Black

font_size

Integer

参数解释

字体大小。接口的取值范围为0-120,实际业务使用的取值范围要求为24-120,请以业务实际使用要求为准。

约束限制

不涉及。

取值范围:

0-120

默认取值:

54

font_color

String

参数解释

字幕字体颜色的RGB颜色值。

约束限制

取值范围

字符长度0-7位,固定长度

默认取值:

#FFFFFF

stroke_color

String

参数解释

字幕字体描边颜色的RGB颜色值。

约束限制

取值范围

字符长度0-7位,固定长度

stroke_thickness

Float

参数解释

字幕字体描边粗细像素值。

约束限制

取值范围

0-50

取值范围:

0-50

opacity

Float

参数解释

字幕字体不透明度,0表示完全透明,1表示完全不透明。默认1。

约束限制

取值范围

0-1

取值范围:

0-1

默认取值:

1

表8 BackgroundMusicConfig

参数

参数类型

描述

music_asset_id

String

参数解释

音乐资产ID。

约束限制

不涉及。

取值范围

字符长度0-64位。

默认取值

不涉及。

volume

Integer

参数解释

音乐音量。如100,表示音量100%,50表示音量50%。

约束限制

不涉及。

取值范围:

0-100

默认取值:

100

表9 ReviewConfig

参数

参数类型

描述

no_need_review

Boolean

免审核。 目前仅白名单用户可使用此参数,非白名单用户跟随系统策略审核。

表10 ShootScriptAudioFiles

参数

参数类型

描述

audio_file_url

Array of ShootScriptAudioFileItem objects

用于语音驱动的音频文件上传URL。

表11 ShootScriptAudioFileItem

参数

参数类型

描述

sequence_no

Integer

剧本序号。

取值范围:

0-2147483647

audio_file_upload_url

String

语音驱动音频文件上传URL。创建和更新脚本时返回。单个文件最大100M。支持上传MP3/WAV/M4A文件。

audio_file_download_url

String

语音驱动音频文件下载URL。查询脚本详情时返回。

audio_id

Integer

audio id

取值范围:

0-10000

表12 ActionConfig

参数

参数类型

描述

action_interval

Float

算法自动插入无语义动作的时间间隔。这个参数填0或者不填默认是间隔4秒,设置成255时不自动插入无语义动作。

取值范围:

0-255

默认取值:

0

表13 ShootScriptShowItem

参数

参数类型

描述

sequence_no

Integer

参数解释

剧本序号。

约束限制

同一个剧本序号不重复。

默认取值

不涉及。

取值范围:

0-2147483647

shoot_script

ShootScriptDetail object

剧本配置

subtitle_file_info

SubtitleFiles object

字幕文件信息。

audio_config

AudioInfo object

音频文件信息。

preview_info

PreviewInfo object

预览信息。

表14 ShootScriptDetail

参数

参数类型

描述

script_type

String

参数解释

脚本类型,即视频制作的驱动方式

约束限制

不涉及

取值范围

  • TEXT: 文本驱动,即通过TTS合成语音

  • AUDIO: 语音驱动

默认取值:

TEXT

text_config

TextConfig object

讲解词配置。

audio_duration

Float

语音驱动时,音频时长,单位秒。

说明:
  • 创建剧本时此参数可以不设置,音频文件上传成功后,通过更新剧本接口设置

  • 查询剧本详情时,返回音频时长,用于预估视频时长

取值范围:

0-36000

audio_drive_action_config

Array of AudioDriveActionConfig objects

语音驱动时的动作配置。

audio_drive_file_external_url

String

语音驱动音频文件外部下载URL。

说明:
  • 只支持分身数字人视频制作

  • 需要先申请开通白名单后,才允许通过外部URL的音频文件来驱动分身数字人视频。

  • 音频文件需要存放在华为云OBS

background_config

Array of BackgroundConfigInfo objects

背景配置。

layer_config

Array of LayerConfig objects

图层配置。

audio_config

AudioInfo object

音频文件信息。

thumbnail_url

String

参数解释

剧本场景缩略图url。

约束限制

不涉及。

取值范围

字符长度1-2048位。

默认取值

不涉及。

表15 TextConfig

参数

参数类型

描述

text

String

参数解释

台词脚本。支持两种模式,纯文本模式和标签模式。

  • 纯文本模式:使用方法,如“大家好,我是人工智大家,是个虚拟主播”。

  • 标签模式:SSML标签的详细定义请参考文本驱动SSML定义

约束限制

不含SSML标签字符数最长10000个字符。

取值范围

字符长度0-131072位。

默认取值

不涉及。

表16 AudioDriveActionConfig

参数

参数类型

描述

action_tag

String

动作标签

action_name

String

动作名称

action_start_time

Float

动作开始时间

取值范围:

0-2592000

表17 BackgroundConfigInfo

参数

参数类型

描述

background_type

String

参数解释

背景类型。

约束限制

不涉及。

取值范围

  • IMAGE:图片背景,指定图片用作分身数字人背景。

  • COLOR:纯色背景,指定颜色RGB值作为分身数字人背景。

默认取值

不涉及

background_config

String

参数解释

背景文件的URL。

约束限制

  • 仅直播支持外部URL,其他业务通过资产库查询获取,不支持外部URL。

  • background_type=IMAGE时需要填写。

取值范围

字符长度1-2048位

默认取值

不涉及。

background_color_config

String

参数解释

纯色背景的RGB颜色值。

约束限制

background_type=COLOR时需要填写。

取值范围

字符长度0-16位

默认取值:

#FFFFFF

background_asset_id

String

参数解释

背景资产ID。

说明:
背景是背景图片时,填图片资产ID。

约束限制

不涉及

取值范围

字符长度0-64位

默认取值

不涉及

background_image_config

BackgroundImageConfig object

背景图片大小及位置配置。

表18 BackgroundImageConfig

参数

参数类型

描述

dx

Integer

参数解释

背景图片左上角像素点的X轴位置值(画布左上角坐标是0x0)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

需要保证背景图片要铺满画布。即dx <= 0,并且横屏时dx + width >=1920,竖屏时dx + width >=1080。

取值范围:

-5760-0

默认取值:

0

dy

Integer

参数解释

背景图片左上角像素点的Y轴位置值(画布左上角坐标是0x0)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

需要保证背景图片要铺满画布。即dy <= 0,并且横屏时dy + height >=1080,竖屏时dy + height >=1920。

取值范围:

-5760-0

默认取值:

0

width

Integer

参数解释

背景图片宽度像素值(相对画布大小)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

需要保证背景图片要铺满画布。即width > 1080,并且横屏时dx + width >=1920,竖屏时dx + width >=1080。

取值范围:

1-7680

height

Integer

参数解释

背景图片高度像素值(相对画布大小)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

需要保证背景图片要铺满画布。height> 1080,并且横屏时dy + height >=1080,竖屏时dy + height >=1920。

取值范围:

1-7680

表19 LayerConfig

参数

参数类型

描述

layer_type

String

参数解释

图层类型。

约束限制

不涉及。

取值范围

  • HUMAN: 人物图层

  • IMAGE: 素材图片图层

  • VIDEO: 素材视频图层

  • TEXT: 素材文字图层

默认取值

不涉及

asset_id

String

参数解释

图层所需资产的资产id,外部资产信息无需填写。

约束限制

不涉及。

取值范围

字符长度0-64位

默认取值

不涉及

group_id

String

参数解释

多场景素材编组。同一group_id的素材,在应用全局时共享位置信息。

约束限制

不涉及。

取值范围

字符长度0-64位

默认取值

不涉及

sequence_no

Integer

参数解释

播放到对应的段落,显示对应的图层。该字段向前兼容,可以不填,字段可选。

只支持直播业务。

约束限制

段落sequence_no。

默认取值

不涉及。

取值范围:

0-2147483647

position

LayerPositionConfig object

图层位置配置。

size

LayerSizeConfig object

图层大小配置。

rotation

LayerRotationConfig object

图层旋转配置。

image_config

ImageLayerConfig object

素材图片图层配置。

video_config

VideoLayerConfig object

素材视频图层配置。

text_config

TextLayerConfig object

素材文字图层配置。

表20 LayerPositionConfig

参数

参数类型

描述

dx

Integer

参数解释

图层左上角像素点的X轴位置值(画布左上角坐标是0x0)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

该值为相对于画布的像素值,仅表示布局位置关系,与输出画面分辨率无关。

取值范围:

-1920-3840

默认取值:

0

dy

Integer

参数解释

图层图片左上角像素点的Y轴位置值(画布左上角坐标是0x0)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

该值为相对于画布的像素值,仅表示布局位置关系,与输出画面分辨率无关。

取值范围:

-1920-3840

默认取值:

0

layer_index

Integer

参数解释

图片、视频、人物图的层顺序。

说明:
图层顺序为从1开始的整数,底层图层顺序是1,往上依次增加。

约束限制

如果出现重复则重复图层叠加关系随机。

取值范围:

1-100

默认取值:

100

表21 LayerSizeConfig

参数

参数类型

描述

width

Integer

参数解释

图层图片左上角像素点的Y轴位置值图层图片宽度像素值(相对画布大小)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

该值为相对于画布的像素值,仅表示布局位置关系,与输出画面分辨率无关。

取值范围:

1-7680

height

Integer

参数解释

图层图片高度像素值(相对画布大小)。

横屏(16:9)画布像素为1920x1080;竖屏(9:16)画布像素为1080x1920。

约束限制

该值为相对于画布的像素值,仅表示布局位置关系,与输出画面分辨率无关。|

取值范围:

1-7680

表22 LayerRotationConfig

参数

参数类型

描述

angle

Integer

参数解释

旋转角度。

取值范围

角度范围0-360度。

默认取值

0度。

约束限制

以素材中心点旋转。

视频素材不支持旋转

取值范围:

0-360

表23 ImageLayerConfig

参数

参数类型

描述

image_url

String

参数解释

图片文件的URL。

约束限制

  • 仅直播支持外部URL,其他业务通过资产库查询获取,不支持外部URL。

取值范围

字符长度1-2048位。

默认取值

不涉及

表24 VideoLayerConfig

参数

参数类型

描述

video_url

String

参数解释

视频文件的URL。

约束限制

  • 仅直播支持外部URL,其他业务通过资产库查询获取,不支持外部URL。

取值范围

字符长度1-2048位。

默认取值

不涉及。

video_cover_url

String

参数解释

视频封面文件的URL。

约束限制

  • 仅直播支持外部URL,其他业务通过资产库查询获取,不支持外部URL。

取值范围

字符长度1-2048位。

默认取值

不涉及。

loop_count

Integer

参数解释

循环播放视频次数。

特殊取值:

  • 0:表示不播放

  • -1:表示持续循环播放

约束限制

不涉及。

取值范围:

-1-100

默认取值:

-1

video_sound

Integer

参数解释

视频声音大小,0 - 100,表示开启视频声音原视频音量的百分比

特殊取值:

  • 0:表示不开启声音(默认值)

约束限制

不涉及。

取值范围:

0-100

is_play_the_entire_video

Boolean

参数解释

是否播放完整个视频,true表示播放完整个视频,false表示当场景文本/音频结束时,视频也同时不再播放。

特殊取值:

默认值为false

约束限制

不涉及。

表25 TextLayerConfig

参数

参数类型

描述

text_context

String

参数解释

文字图层的文本,内容需做Base64编码。

示例:若想添加文字水印“测试文字水印”,那么text_context的值为:5rWL6K+V5paH5a2X5rC05Y2w

约束限制

不涉及。

取值范围

字符长度0-1024位。

默认取值

不涉及。

font_name

String

字体。当前支持的字体请参考服务支持的字体

约束限制

不涉及。

取值范围

字符长度0-64位

默认取值:

HarmonyOS_Sans_SC_Black

font_size

Integer

参数解释

字体大小(像素)。接口的取值范围为0-120,实际业务使用的取值范围要求为4-120,请以业务实际使用要求为准。

约束限制

不涉及。

取值范围:

0-120

默认取值:

16

font_color

String

参数解释

字体颜色。RGB颜色值。

约束限制

不涉及。

取值范围

字符长度0-16位

默认取值:

#FFFFFF

表26 SubtitleFiles

参数

参数类型

描述

text_subtitle_file

SubtitleFileInfo object

audio_subtitle_file

SubtitleFileInfo object

表27 SubtitleFileInfo

参数

参数类型

描述

subtitle_file_download_url

String

字幕文件下载链接。

subtitle_file_upload_url

String

字幕文件上传链接。

subtitle_file_state

String

字幕文件生成状态。

  • GENERATING:字幕文件生成中。

  • GENERATE_SUCCEED:字幕文件生成成功。

  • GENERATE_FAILED:字幕文件生成失败。

job_id

String

字幕文件生成任务ID。

表28 AudioInfo

参数

参数类型

描述

audio_id

Integer

参数解释

音频id。

说明:
  • 获取方式:剧本为音频驱动时,查询剧本详情或者更新剧本会返回audio_id

约束限制

不涉及

默认取值

不涉及

取值范围:

0-10000

表29 PreviewInfo

参数

参数类型

描述

text_sha256

String

文本内容hash值

audio_file_download_url

String

文本对应音频文件下载链接

action_file_download_url

String

动作编排列表文件下载链接

audio_duration

Float

音频时长,单位秒。

取值范围:

0-36000

状态码:400

表30 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码:401

表31 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码:404

表32 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码:500

表33 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

请求示例

GET https://{endpoint}/v1/70b76xxxxxx34253880af501cdxxxxxx/digital-human-video-scripts/24bad716-87b1-45e5-8912-6102f7693265

响应示例

状态码:200

成功。

{
  "script_name" : "大自然的传说",
  "script_description" : "课件",
  "model_asset_id" : "a5d295cdb345c11bd9f36bc22ced3a7a",
  "voice_config" : {
    "voice_asset_id" : "a5d295cdb345c11bd9f36bc22ced3a7a",
    "speed" : 100,
    "pitch" : 100,
    "volume" : 140
  },
  "video_config" : {
    "codec" : "H264",
    "bitrate" : 4000,
    "frame_rate" : "25",
    "width" : 1920,
    "height" : 1080
  },
  "shoot_scripts" : [ {
    "sequence_no" : 0,
    "shoot_script" : {
      "text_config" : {
        "text" : "大家好,我是云笙"
      },
      "background_config" : [ {
        "background_type" : "IMAGE",
        "background_config" : "978f893e1de4553c183b7a805e6290f5"
      } ]
    }
  } ]
}

状态码:400

请求传参异常,包含错误码及对应描述。

{
  "error_code" : "MSS.00000003",
  "error_msg" : "Invalid parameter"
}

状态码:401

未鉴权或鉴权失败。

{
  "error_code" : "MSS.00000001",
  "error_msg" : "Unauthorized"
}

状态码:404

无内容。

{
  "error_code" : "MSS.00000002",
  "error_msg" : "Not Found"
}

状态码:500

内部服务错误。

{
  "error_code" : "MSS.00000004",
  "error_msg" : "Internal Error"
}

状态码

状态码

描述

200

成功。

400

请求传参异常,包含错误码及对应描述。

401

未鉴权或鉴权失败。

404

无内容。

500

内部服务错误。

错误码

请参见错误码