Creating a Virtual Avatar Video Production Task

Function

Creates a virtual avatar video production task.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/2d-digital-human-videos

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token. This parameter is mandatory when token authentication is used. You can obtain the token by calling the IAM API used to obtain a user token. Value of X-Subject-Token in the response header.
Authorization	No	String	Authentication information. This parameter is mandatory for AK/SK authentication.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory for AK/SK authentication. The format is YYYYMMDD'T'HHMMSS'Z'.
X-Project-Id	No	String	Project ID. This parameter is mandatory for AK/SK authentication.
X-App-UserId	No	String	Third-party user ID, which does not allow Chinese characters.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
script_id	No	String	Script ID. NOTE: If script_id is specified, model_asset_id, voice_config, scene_asset_id, video_config, and shoot_scripts are optional. Use the settings in the script. If script_id, model_asset_id, voice_config, scene_asset_id, video_config, and shoot_scripts are specified, use the settings in the script.
model_asset_id	No	String	Asset ID of a virtual avatar model.
voice_config	No	VoiceConfig object	Timbre configuration.
video_config	No	VideoConfig object	Video output configuration.
shoot_scripts	No	Array of ShootScriptItem objects	Shooting script list.
output_asset_config	No	OutputAssetConfig object	Output asset information configuration.
background_music_config	No	BackgroundMusicConfig object	Background music configuration.
review_config	No	ReviewConfig object	Configures content review.
callback_config	No	CallBackConfig object	Callback setting.

**Table 4** VoiceConfig
Parameter	Mandatory	Type	Description
voice_asset_id	Yes	String	Timbre asset ID.
speed	No	Integer	Speech speed. The value defaults to 100 and ranges from 50 to 200. NOTE: The value 100 indicates the normal speaking speed of an adult, which is about 250 words per minute. 50 indicates 0.5x speaking speed, 100 indicates normal speaking speed, and 200 indicates 2x speaking speed.
pitch	No	Integer	Pitch. The value defaults to 100 and ranges from 50 to 200.
volume	No	Integer	Volume. The value defaults to 140 and ranges from 90 to 240.

**Table 5** VideoConfig
Parameter	Mandatory	Type	Description
clip_mode	No	String	Clipping mode of the output video. Default value: RESIZE. RESIZE: video scaling CROP: video cropping
codec	Yes	String	Video encoding format and video file format. H264: H.264 encoding, MP4 file output VP8: VP8 encoding, WebM file output
bitrate	Yes	Integer	Average output bitrate. Unit: kbit/s The value ranges from 40 to 30,000. NOTE: Quality is prioritized for virtual avatar video production, which may exceed the preset bitrate. Bitrate range for virtual avatar video production: [1000, 8000].
width	Yes	Integer	Video width. Unit: pixel. NOTE: When clip_mode is set to RESIZE, the following resolutions are supported: 1920 x 1080, 1080 x 1920, 1280 x 720, 720 x 1280, 3840 x 2160, and 2160 x 3840. 4K videos can be used only when the virtual avatar model supports 4K. When clip_mode is set to CROP, (dx, dy) is the origin, and the width is the actual width of the reserved video. Currently, only 1080 x 1920 is supported for virtual avatar livestreaming.
height	Yes	Integer	Video height. Unit: pixel. NOTE: When clip_mode is set to RESIZE, the following resolutions are supported: 1920 x 1080, 1080 x 1920, 1280 x 720, 720 x 1280, 3840 x 2160, and 2160 x 3840. When clip_mode is set to CROP, (dx, dy) is the origin, and the height is the actual height of the reserved video. Currently, only 1080 x 1920 is supported for virtual avatar livestreaming.
frame_rate	No	String	Frame rate. Unit: FPS NOTE: The frame rate of virtual avatar videos is fixed at 25 FPS.
is_subtitle_enable	No	Boolean	Whether the output video is subtitled. The default value is false. true: Displays the subtitle. false: Hides the subtitle.
subtitle_config	No	SubtitleConfig object	Subtitle configuration.
dx	No	Integer	Coordinates of the pixel in the upper left corner of the cropped video. This parameter takes effect when clip_mode is set to crop. NOTE: The canvas size is based on the model resolution. For example, for a model with the resolution of 1920 x 1080, the value of dx ranges from 0 to 1920.
dy	No	Integer	Coordinates of the pixel in the upper left corner of the cropped video. This parameter takes effect when clip_mode is set to crop. NOTE: The canvas size is based on the model resolution. For example, for a model with the resolution of 1920 x 1080, the value of dy ranges from 0 to 1080.
is_enable_super_resolution	No	Boolean	Whether super resolution is enabled for a video. NOTE: true: enable false: do not enable

**Table 6** SubtitleConfig
Parameter	Mandatory	Type	Description
dx	No	Integer	Coordinates of the pixel in the lower left corner of the subtitle. NOTE: The video resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).
dy	No	Integer	Coordinates of the pixel in the lower left corner of the subtitle. NOTE: The video resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).
font_name	No	String	Font. The following fonts are supported: HarmonyOS_Sans_SC_Black: HarmonyOS bold HarmonyOS_Sans_SC_Regular: HarmonyOS normal HarmonyOS_Sans_SC_Thin: HarmonyOS light
font_size	No	Integer	Font size. The value ranges from 4 to 120.
h	No	Integer	Subtitle box height NOTE: The parameter h is used to facilitate the calculation of the coordinates in the upper left corner of the subtitle box by the front end. This parameter is not used in the background.
w	No	Integer	Subtitle box width NOTE: The subtitle box width is fixed at 80/ %of the screen width. The parameter w is used to facilitate the calculation of the coordinates in the upper left corner of the subtitle box by the front end. This parameter is not used in the background.

**Table 7** ShootScriptItem
Parameter	Mandatory	Type	Description
sequence_no	No	Integer	Script No.
shoot_script	Yes	ShootScript object	Performance script.

**Table 8** ShootScript
Parameter	Mandatory	Type	Description
script_type	No	String	Script type, that is, the control mode of video production. The default value is TEXT. TEXT: text control, that is, voice compositing through TTS AUDIO: speech control
text_config	No	TextConfig object	Commentary configuration.
background_config	No	Array of BackgroundConfigInfo objects	Background configuration.
layer_config	No	Array of LayerConfig objects	Layer configuration.

**Table 9** TextConfig
Parameter	Mandatory	Type	Description
text	Yes	String	Script. Two modes are supported: plain text mode and tag mode. Plain text mode Plain text mode, for example, "Hello, everyone, I'm a virtual streamer." Tag mode For details about the definition of SSML tags, see SSML Definition of Text Control.

**Table 10** BackgroundConfigInfo
Parameter	Mandatory	Type	Description
background_type	Yes	String	Background type. IMAGE: image, which is used as the image for 3D virtual human demonstration materials or virtual avatar background. IMAGE_2D: image, which is used as the background image in the 2D scene for 3D virtual broadcasters. VIDEO: video AUDIO: audio NOTE: Only IMAGE is supported for virtual avatar video production.
background_config	No	String	Background file URL. NOTE: External URLs are allowed only for livestreaming. For other services, obtain a URL from the asset library. This parameter is mandatory when background_type is set to IMAGE.
background_color_config	No	String	RGB color value of a solid color background. NOTE: This parameter is mandatory when background_type is set to COLOR.
background_asset_id	No	String	Background asset ID. NOTE: If the background is a background image, set this parameter to the image asset ID.

**Table 11** LayerConfig
Parameter	Mandatory	Type	Description
layer_type	Yes	String	Layer type. HUMAN: person layer IMAGE: image layer VIDEO: video layer TEXT: material text layer
asset_id	No	String	ID of the asset overlaid on a video. You do not need to set this parameter for external assets.
group_id	No	String	Groups materials in multiple scenes. Materials with the same group_id share location information when they are applied globally.
position	No	LayerPositionConfig object	Layer position configuration.
size	No	LayerSizeConfig object	Layer size configuration.
image_config	No	ImageLayerConfig object	Material image layer configuration.
video_config	No	VideoLayerConfig object	Material video layer configuration.
text_config	No	TextLayerConfig object	Material text layer configuration.

**Table 12** LayerPositionConfig
Parameter	Mandatory	Type	Description
dx	Yes	Integer	X axis position of the pixel in the upper left corner of the image. The coordinate of the upper left corner of the canvas is 0x0. NOTE: The canvas resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).
dy	Yes	Integer	Y axis position of the pixel in the upper left corner of the image. The coordinate of the upper left corner of the canvas is 0x0. NOTE: The canvas resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).
layer_index	Yes	Integer	Layer sequence of an image, video, or person image. NOTE: The layer sequence is an integer starting from 1. The sequence of the bottom layer is 1 and incremented by 1.

**Table 13** LayerSizeConfig
Parameter	Mandatory	Type	Description
width	No	Integer	Width (in pixel) of the layer image (relative to the canvas size). NOTE: The canvas resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).
height	No	Integer	Height (in pixel) of the layer image (relative to the canvas size). NOTE: The canvas resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16).

**Table 14** ImageLayerConfig
Parameter	Mandatory	Type	Description
image_url	No	String	Image file URL.

**Table 15** VideoLayerConfig
Parameter	Mandatory	Type	Description
video_url	No	String	Video file URL.
video_cover_url	No	String	Video thumbnail file URL.
loop_count	No	Integer	Number of times that a video is played cyclically.

**Table 16** TextLayerConfig
Parameter	Mandatory	Type	Description
text_context	No	String	Text of the text layer. The content must be encoded using Base64. For example, if you want to add the text watermark "Test text watermark", set text_context to 5rWL6K+V5paH5a2X5rC05Y2w.
font_name	No	String	Font. The following fonts are supported: HarmonyOS_Sans_SC_Black: HarmonyOS bold HarmonyOS_Sans_SC_Regular: HarmonyOS normal HarmonyOS_Sans_SC_Thin: HarmonyOS light fzyouh: Square & lean
font_size	No	Integer	Font size (pixel). The value ranges from 4 to 120.
font_color	No	String	Font color. RGB color value.

**Table 17** OutputAssetConfig
Parameter	Mandatory	Type	Description
asset_name	Yes	String	Output video asset name.

**Table 18** BackgroundMusicConfig
Parameter	Mandatory	Type	Description
music_asset_id	No	String	Music asset ID.
volume	No	Integer	Music volume. For example, 100 indicates that the volume is 100%, and 50 indicates that the volume is 50%. The value defaults to 100 and ranges from 0 to 100.

**Table 19** ReviewConfig
Parameter	Mandatory	Type	Description
no_need_review	No	Boolean	Content review whitelist. This feature is available only for users in the whitelist. The auto review policies apply to other users.

**Table 20** CallBackConfig
Parameter	Mandatory	Type	Description
callback_url	Yes	String	Callback URL. The callback request body is in JSON format and contains the following parameters: result: SUCCEED or FAILED asset_id: asset ID job_id: task
auth_type	No	String	Authentication type. None: The URL contains authentication. MSS_A: In HMACSHA256 signature mode, the secret and time_stamp parameters are added to the URL. Value format: secret=hmac_sha256(key, URI (callback_url) + time_stamp)&time_stamp=hex(timestamp)
key	No	String	Key

Response Parameters

Status code: 200

**Table 21** Response header parameters
Parameter	Type	Description
X-Request-Id	String	Request ID.

**Table 22** Response body parameters
Parameter	Type	Description
job_id	String	Task ID.

Status code: 400

**Table 23** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 401

**Table 24** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 500

**Table 25** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Example Requests

POST https://{endpoint}/v1/0d697589d98091f12f92c0073501cd79/2d-digital-human-videos

{
  "model_asset_id" : "0c7798664ee7178b3dba3bbef57c32e7",
  "voice_config" : {
    "voice_asset_id" : "394f3a27cd0b3d6164ca75c3db1edf6c",
    "speed" : 100,
    "pitch" : 100,
    "volume" : 140
  },
  "video_config" : {
    "codec" : "H264",
    "bitrate" : 5000,
    "width" : 1920,
    "height" : 1080,
    "frame_rate" : "30"
  },
  "shoot_scripts" : [ {
    "sequence_no" : 0,
    "shoot_script" : {
      "text_config" : {
        "text" : "Hello, everyone. I'm Yunling."
      },
      "background_config" : [ {
        "background_type" : "IMAGE",
        "background_config" : "https://{endpoint}/0d697589d98091f12f92c0073501cd79/c7885ffdfb347337a890208ca7fd07e3/34534f0262813a6838bdcfb8bc949af6.jpg?AccessKeyId=WTEZCVDFUF3XHXCTPIJ8&Expires=1686872878&Signature=zXGOEQlrgZ4yAUziwlGcdbXLPIM%3D",
        "human_position_2d" : {
          "position" : "MIDDLE"
        }
      } ]
    }
  } ],
  "output_asset_config" : {
    "asset_name" : "Yunling's self-introduction."
  }
}

Example Responses

Status code: 200

The information is returned when the request succeeds.

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

Status code: 400

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

Status code: 401

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

Status code: 500

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

Status Codes

Status Code	Description
200	The information is returned when the request succeeds.
400	Parameters error, including the error code and its description.
401	Authentication is not performed or fails.
500	Internal service error.