Help Center/ MetaStudio/ API Reference/ Virtual Avatar Video Production/ Virtual avatar video production management/ Querying Virtual Avatar Video Production Task Details

Updated on 2024-07-04 GMT+08:00

Online Debugging

CLI Examples

View PDF

Querying Virtual Avatar Video Production Task Details

Function

Queries virtual avatar video production task details.

Calling Method

For details, see Calling APIs.

URI

GET /v1/{project_id}/2d-digital-human-videos/{job_id}

**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.
job_id	Yes	String	Task ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
show_script	No	Boolean	Whether to return the script parameter configuration.

Request Parameters

**Table 3** 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.

Response Parameters

Status code: 200

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

**Table 5** Response body parameters
Parameter	Type	Description
job_id	String	Task ID.
state	String	Task status. Options: WAITING: The task is waiting for execution. PROCESSING: The task is being processed. SUCCEED: Task execution succeeded. FAILED: Task execution failed. CANCELED: The task has been canceled. BLOCK: The task has been frozen.
job_type	String	Task type. 2D_DIGITAL_HUMAN_VIDEO: virtual avatar video production task PHOTO_DIGITAL_HUMAN_VIDEO: photo-based virtual human video production
start_time	String	Start time of virtual human video production.
end_time	String	End time of virtual human video production.
duration	Float	Virtual human video duration.
output_asset_config	OutputAssetInfo object	Output asset information.
error_info	ErrorResponse object	Error message.
create_time	String	Task creation time.
lastupdate_time	String	Task update time.
script_id	String	Script ID.
video_making_type	String	Video generation mode. If this parameter is set to MODEL, model_asset_id is mandatory. If this parameter is set to PICTURE, human_image is mandatory. MODEL: Generates a video from a virtual avatar model. PICTURE: Generates a video from one photo. NOTE: This parameter has been discarded. The API for creating a photo-based virtual avatar video production task will be used.
human_image	String	Person photo, which must be encoded using Base64. NOTE: This parameter has been discarded. The API for creating a photo-based virtual avatar video production task will be used.
model_asset_id	String	Asset ID of a virtual avatar model.
voice_config	VoiceConfig object	Voice configuration parameter.
video_config	VideoConfig object	Video output configuration.
shoot_scripts	Array of ShootScriptItem objects	Shooting script list.
background_music_config	BackgroundMusicConfig object	Background music configuration.

**Table 6** OutputAssetInfo
Parameter	Type	Description
asset_id	String	Output video asset ID.
asset_name	String	Output video asset name.
cover_url	String	Video thumbnail URL.
preview_video_url	String	URL for downloading a preview video. The validity period of the URL is 24 hours. NOTE: Virtual avatar videos do not support preview.

**Table 7** ErrorResponse
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

**Table 8** VoiceConfig
Parameter	Type	Description
voice_asset_id	String	Timbre asset ID.
speed	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	Integer	Pitch. The value defaults to 100 and ranges from 50 to 200.
volume	Integer	Volume. The value defaults to 140 and ranges from 90 to 240.

**Table 9** VideoConfig
Parameter	Type	Description
clip_mode	String	Clipping mode of the output video. Default value: RESIZE. RESIZE: video scaling CROP: video cropping
codec	String	Video encoding format and video file format. H264: H.264 encoding, MP4 file output VP8: VP8 encoding, WebM file output
bitrate	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	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	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	String	Frame rate. Unit: FPS NOTE: The frame rate of virtual avatar videos is fixed at 25 FPS.
is_subtitle_enable	Boolean	Whether the output video is subtitled. The default value is false. true: Displays the subtitle. false: Hides the subtitle.
subtitle_config	SubtitleConfig object	Subtitle configuration.
dx	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	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	Boolean	Whether super resolution is enabled for a video. NOTE: true: enable false: do not enable

**Table 10** SubtitleConfig
Parameter	Type	Description
dx	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	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	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	Integer	Font size. The value ranges from 4 to 120.
h	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	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 11** ShootScriptItem
Parameter	Type	Description
sequence_no	Integer	Script No.
shoot_script	ShootScript object	Performance script.

**Table 12** ShootScript
Parameter	Type	Description
script_type	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	TextConfig object	Commentary configuration.
background_config	Array of BackgroundConfigInfo objects	Background configuration.
layer_config	Array of LayerConfig objects	Layer configuration.

**Table 13** TextConfig
Parameter	Type	Description
text	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 14** BackgroundConfigInfo
Parameter	Type	Description
background_type	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	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	String	RGB color value of a solid color background. NOTE: This parameter is mandatory when background_type is set to COLOR.
background_asset_id	String	Background asset ID. NOTE: If the background is a background image, set this parameter to the image asset ID.

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

**Table 16** LayerPositionConfig
Parameter	Type	Description
dx	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	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	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 17** LayerSizeConfig
Parameter	Type	Description
width	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	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 18** ImageLayerConfig
Parameter	Type	Description
image_url	String	Image file URL.

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

**Table 20** TextLayerConfig
Parameter	Type	Description
text_context	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	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	Integer	Font size (pixel). The value ranges from 4 to 120.
font_color	String	Font color. RGB color value.

**Table 21** BackgroundMusicConfig
Parameter	Type	Description
music_asset_id	String	Music asset ID.
volume	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.

Status code: 400

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

Status code: 401

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

Status code: 404

**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

GET https://{endpoint}/v1/0d697589d98091f12f92c0073501cd79/2d-digital-human-videos/26f06524-4f75-4b3a-a853-b649a21aaf66

Example Responses

Status code: 200

The information is returned when the request succeeds.

{
  "job_id" : "26f06524-4f75-4b3a-a853-b649a21aaf66",
  "state" : "SUCCESS",
  "start_time" : "2022-01-18T16:29:36Z",
  "end_time" : "2022-01-18T16:30:36Z",
  "duration" : 60,
  "output_asset_config" : {
    "asset_id" : "942e65a5fd219a2e01fb08d881cfadb9",
    "asset_name" : "One Day",
    "cover_url" : "https://{endpoint}/0d697589d98091f12f92c0073501cd79/942e65a5fd219a2e01fb08d881cfadb9/20d367508e62d3d4ad608cedbe81bd35.png?AccessKeyId=XCQKTA8IWQPCAUQS4SDA&Expires=1671241457&Signature=zVGMVbI5ji9rr8epD1Cir5OGIRk%3D"
  },
  "error_info" : null,
  "create_time" : "2022-11-30T06:59:56Z",
  "lastupdate_time" : "2022-11-30T07:00:09Z",
  "script_id" : "4b5b6effcf3b4c72a0baccb265111765",
  "model_asset_id" : "cda7e9a469ee9cf3ffc1ad62794a12ff",
  "voice_config" : {
    "voice_asset_id" : "f5e6a13eab4443fa85421191ad061780",
    "speed" : 100,
    "pitch" : 100,
    "volume" : 140
  },
  "video_config" : {
    "codec" : "H264",
    "bitrate" : 5000,
    "width" : 720,
    "height" : 1280,
    "frame_rate" : 30
  },
  "shoot_scripts" : [ {
    "sequence_no" : 0,
    "shoot_script" : {
      "text_config" : {
        "text" : "Hello, everyone. I'm Yunling."
      },
      "background_config" : [ {
        "human_position_2d" : {
          "position" : "MIDDLE"
        },
        "background_type" : "IMAGE",
        "background_config" : "https://{endpoint}/0d697589d98091f12f92c0073501cd79/c7885ffdfb347337a890208ca7fd07e3/34534f0262813a6838bdcfb8bc949af6.jpg?AccessKeyId=WTEZCVDFUF3XHXCTPIJ8&Expires=1686901332&Signature=2E7Y7joo2NopBsU8u3iDnf2P9p8%3D"
      } ]
    }
  } ]
}

Status code: 400

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

Status code: 401

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

Status code: 404

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

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.
404	No content.
500	Internal service error.