# 创建照片分身数字人视频制作任务 - CreatePhotoDigitalHumanVideo #### 功能介绍 该接口用于创建照片分身数字人视频制作任务。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-metastudio/metastudio_02_0002.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-metastudio/metastudio_02_0071.html)。 #### URI POST /v1/{project_id}/photo-digital-human-videos 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目ID，获取方法请参考[获取项目ID](https://support.huaweicloud.com/api-metastudio/metastudio_02_0006.html)。 | #### 请求参数 表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。不允许输入中文。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | script_id | 否 | String | 剧本ID。 说明： - 如果shoot_scripts中shoot_script.script_type为"TEXT"，则台词以shoot_scripts中的文本为准； - 如果shoot_scripts中shoot_script.script_type为"AUDIO"，则台词以script_id对应剧本中的音频为准。 | | human_image | 是 | String | 人物照片，需要Base64编码。照片分辨率不超过1080P。 | | voice_config | 否 | [VoiceConfig] object | 音色配置。 | | video_config | 否 | [PhotoVideoConfig] object | 视频输出配置。 | | shoot_scripts | 是 | Array of [ShootScriptItem] objects | 剧本列表。照片数字人仅支持传入一个剧本shoot_script，剧本参数仅支持shoot_script.script_type、shoot_script.text_config； | | output_asset_config | 是 | [OutputAssetConfig] object | 输出资产信息配置。 | | background_music_config | 否 | [BackgroundMusicConfig] object | 背景音乐配置。 | | review_config | 否 | [ReviewConfig] object | 内容审核配置 | | callback_config | 否 | [CallBackConfig] object | 回调设置。 | | id_card_image1 | 否 | String | 身份证国徽面照片，需要Base64编码。 | | id_card_image2 | 否 | String | 身份证人像面照片，需要Base64编码。 | | authorize_use_human_image | 否 | Boolean | 授权使用照片 | 表4VoiceConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | voice_asset_id | 是 | String | **参数解释**： 音色资产ID，可以从资产库中查询。 音色ID的查询操作，详见[查询预置音色ID](https://support.huaweicloud.com/api-metastudio/metastudio_02_0054.html)。 **约束限制**： 不涉及。 **取值范围**： 字符长度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 | 表5PhotoVideoConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | codec | 是 | String | 视频编码格式及视频文件格式。 - H264：h264编码，输出mp4文件 | | bitrate | 否 | Integer | **参数解释**： 输出平均码率。 单位：kbps。 最小值40，最大值30000。 **取值范围：** 40\~30000 | | frame_rate | 否 | String | 帧率。 单位：FPS。 **默认取值：** 30 | 表6ShootScriptItem | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | sequence_no | 否 | Integer | **参数解释**： 剧本序号。 **约束限制**： 同一个剧本序号不重复。 **默认取值**： 不涉及。 **取值范围：** 0\~2147483647 | | shoot_script | 是 | [ShootScript] object | 表演脚本。 | | subtitle_file_info | 否 | [SubtitleFiles] object | 字幕文件信息。 | 表7ShootScript | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 图层配置。 说明： - 视频编码格式采用VP8且数字人模型和输出视频的分辨率不一致时，该参数必须携带 | | audio_config | 否 | [AudioInfo] object | 音频文件信息。 | 表8TextConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | text | 是 | String | **参数解释**： 台词脚本。支持两种模式，纯文本模式和标签模式。 - 纯文本模式：使用方法，如"大家好，我是人工智大家，是个虚拟主播"。 - 标签模式：SSML标签的详细定义请参考[文本驱动SSML定义](https://support.huaweicloud.com/api-metastudio/metastudio_02_0038.html)。 **约束限制**： 不含SSML标签字符数最长10000个字符。 **取值范围**： 字符长度0-131072位。 **默认取值**： 不涉及。 | 表9AudioDriveActionConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | action_tag | 是 | String | 动作标签 | | action_name | 否 | String | 动作名称 | | action_start_time | 是 | Float | 动作开始时间 **取值范围：** 0\~2592000 | 表10BackgroundConfigInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | background_type | 是 | String | **参数解释**： 背景类型。 **约束限制**： 不涉及。 **取值范围**： - IMAGE：图片背景，指定图片用作分身数字人背景。 - COLOR：纯色背景，指定颜色RGB值作为分身数字人背景。 **默认取值**： 不涉及 | | human_position_2d | 否 | [HumanPosition2D] object | 分身数字人在背景图片的位置设置。不设置默认在图片中间。 说明： - 此参数废弃。分身数字人在背景中位置在layer_config参数中配置。 | | human_size_2d | 否 | [HumanSize2D] object | 分身数字人在背景图片的大小设置。 说明： - 此参数废弃。分身数字人在背景中大小在layer_config参数中配置。 | | 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 | 背景图片大小及位置配置。 | 表11HumanPosition2D | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | position | 否 | String | 分身数字人在背景图片中的位置。 - LEFT： 左 - MIDDLE： 中 - RIGHT： 右 说明： 当position_x和position_y参数值存在时，position不生效 **默认取值：** MIDDLE | | position_x | 否 | Integer | 分身数字人X轴位置，即分身数字图片底边中心点像素的X轴的像素值。 横屏（16:9）背景图片像素为1920x1080；竖屏（9:16）背景图片像素为1080x1920。 **取值范围：** -1920\~3840 | | position_y | 否 | Integer | 分身数字Y轴位置，即分身数字图片底边中心点像素的Y轴的像素值。 横屏（16:9）背景图片像素为1920x1080；竖屏（9:16）背景图片像素为1080x1920。 **取值范围：** -1920\~3840 | 表12HumanSize2D | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | width | 否 | Integer | 分身数字人宽度像素值。 横屏（16:9）背景图片像素为1920x1080；竖屏（9:16）背景图片像素为1080x1920。 **取值范围：** 1\~7680 | | height | 否 | Integer | 分身数字人高度像素值。 横屏（16:9）背景图片像素为1920x1080；竖屏（9:16）背景图片像素为1080x1920。 **取值范围：** 1\~7680 | 表13BackgroundImageConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 表14LayerConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 素材文字图层配置。 | 表15LayerPositionConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 表16LayerSizeConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | width | 否 | Integer | **参数解释**： 图层图片左上角像素点的Y轴位置值图层图片宽度像素值（相对画布大小）。 横屏（16:9）画布像素为1920x1080；竖屏（9:16）画布像素为1080x1920。 **约束限制**： 该值为相对于画布的像素值，仅表示布局位置关系，与输出画面分辨率无关。 **取值范围：** 1\~7680 | | height | 否 | Integer | **参数解释**： 图层图片高度像素值（相对画布大小）。 横屏（16:9）画布像素为1920x1080；竖屏（9:16）画布像素为1080x1920。 **约束限制**： 该值为相对于画布的像素值，仅表示布局位置关系，与输出画面分辨率无关。\| **取值范围：** 1\~7680 | 表17LayerRotationConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | angle | 否 | Integer | **参数解释**： 旋转角度。 **取值范围**： 角度范围0-360度。 **默认取值**： 0度。 **约束限制**： 以素材中心点旋转。 视频素材不支持旋转 **取值范围：** 0\~360 | 表18ImageLayerConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_url | 否 | String | **参数解释**： 图片文件的URL。 **约束限制**： - 仅直播支持外部URL，其他业务通过资产库查询获取，不支持外部URL。 **取值范围**： 字符长度1-2048位。 **默认取值**： 不涉及 | 表19VideoLayerConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 **约束限制**： 不涉及。 | 表20TextLayerConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | text_context | 否 | String | **参数解释**： 文字图层的文本，内容需做Base64编码。 示例：若想添加文字水印"测试文字水印"，那么text_context的值为：5rWL6K+V5paH5a2X5rC05Y2w **约束限制**： 不涉及。 **取值范围**： 字符长度0-1024位。 **默认取值**： 不涉及。 | | font_name | 否 | String | 字体。当前支持的字体请参考[服务支持的字体](https://support.huaweicloud.com/api-metastudio/metastudio_02_0041.html) **约束限制**： 不涉及。 **取值范围**： 字符长度0-64位 **默认取值：** HarmonyOS_Sans_SC_Black | | font_size | 否 | Integer | **参数解释**： 字体大小（像素）。接口的取值范围为0-120，实际业务使用的取值范围要求为4-120，请以业务实际使用要求为准。 **约束限制**： 不涉及。 **取值范围：** 0\~120 **默认取值：** 16 | | font_color | 否 | String | **参数解释**： 字体颜色。RGB颜色值。 **约束限制**： 不涉及。 **取值范围**： 字符长度0-16位 **默认取值：** #FFFFFF | 表21AudioInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | audio_id | 否 | Integer | **参数解释**： 音频id。 说明： - 获取方式：剧本为音频驱动时，查询剧本详情或者更新剧本会返回audio_id **约束限制**： 不涉及 **默认取值**： 不涉及 **取值范围：** 0\~10000 | 表22SubtitleFiles | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | text_subtitle_file | 否 | [SubtitleFileInfo] object | | | audio_subtitle_file | 否 | [SubtitleFileInfo] object | | 表23SubtitleFileInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | subtitle_file_download_url | 否 | String | 字幕文件下载链接。 | | subtitle_file_upload_url | 否 | String | 字幕文件上传链接。 | | subtitle_file_state | 否 | String | 字幕文件生成状态。 - GENERATING：字幕文件生成中。 - GENERATE_SUCCEED：字幕文件生成成功。 - GENERATE_FAILED：字幕文件生成失败。 | | job_id | 否 | String | 字幕文件生成任务ID。 | 表24OutputAssetConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | asset_name | 是 | String | **参数解释**： 输出视频资产名称。 说明： - 视频资产名称最大长度支持256；文件名称最大长度支持240（超过长度的会被舍弃） **约束限制**： 不涉及。 **取值范围**： 字符长度0-256位。 **默认取值**： 不涉及。 | 表25BackgroundMusicConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | music_asset_id | 否 | String | **参数解释**： 音乐资产ID。 **约束限制**： 不涉及。 **取值范围**： 字符长度0-64位。 **默认取值**： 不涉及。 | | volume | 否 | Integer | **参数解释**： 音乐音量。如100，表示音量100%，50表示音量50%。 **约束限制**： 不涉及。 **取值范围：** 0\~100 **默认取值：** 100 | 表26ReviewConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | no_need_review | 否 | Boolean | 免审核。 目前仅白名单用户可使用此参数，非白名单用户跟随系统策略审核。 | 表27CallBackConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | callback_url | 是 | String | 回调URL。 回调请求body为json格式，带参数如下： result: SUCCEED或FAILED asset_id: 资产ID job_id: 任务 | | auth_type | 否 | String | 认证类型。 - NONE。URL中自带认证。 - MSS_A。HMACSHA256签名模式，在URL中追加参数:secret,time_stamp。取值方式：secret=hmac_sha256(key, URI（callback_url）+ time_stamp)\&time_stamp=hex(timestamp) **默认取值：** NONE | | key | 否 | String | 密钥Key | #### 响应参数 **状态码：200** 表28响应Header参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | X-Request-Id | String | 请求ID。 | 表29响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | job_id | String | 任务ID。 | **状态码：400** 表30响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误描述。 | **状态码：401** 表31响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误描述。 | **状态码：500** 表32响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误描述。 | #### 请求示例 ``` POST https://{endpoint}/v1/0d697589d98091f12f92c0073501cd79/photo-digital-human-videos { "human_image" : "/9j/4AAQSkZJRgABAQEAYABg...", "voice_config" : { "voice_asset_id" : "394f3a27cd0b3d6164ca75c3db1edf6c", "speed" : 100, "pitch" : 100, "volume" : 140 }, "shoot_scripts" : [ { "sequence_no" : 0, "shoot_script" : { "text_config" : { "text" : "大家好，我是云玲。" } } } ], "video_config" : { "codec" : "H264" }, "output_asset_config" : { "asset_name" : "云玲自我介绍" } } ``` #### 响应示例 **状态码：200** 处理成功返回。 ``` { "job_id" : "26f06524-4f75-4b3a-a853-b649a21aaf66" } ``` **状态码：400** 请求传参异常，包含错误码及对应描述。 ``` { "error_code" : "MSS.00000003", "error_msg" : "Invalid parameter" } ``` **状态码：401** 未鉴权或鉴权失败。 ``` { "error_code" : "MSS.00000001", "error_msg" : "Unauthorized" } ``` **状态码：500** 内部服务错误。 ``` { "error_code" : "MSS.00000004", "error_msg" : "Internal Error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 处理成功返回。 | | 400 | 请求传参异常，包含错误码及对应描述。 | | 401 | 未鉴权或鉴权失败。 | | 500 | 内部服务错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-metastudio/ErrorCode.html)。