Help Center/ MetaStudio/ API Reference/ Virtual Avatar Video Production/ Video Script Management/ Querying Video Script Details
Updated on 2024-07-04 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying Video Script Details

Function

Queries video script details.

Calling Method

For details, see Calling APIs.

URI

GET /v1/{project_id}/digital-human-video-scripts/{script_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.

script_id

Yes

String

Script 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.

Response Parameters

Status code: 200

Table 3 Response header parameters

Parameter

Type

Description

X-Request-Id

String

Request ID.
Table 4 Response body parameters

Parameter

Type

Description

script_name

String

Script name.

script_description

String

Script description.

view_mode

String

Landscape or portrait mode. The default value is LANDSCAPE.

  • LANDSCAPE: landscape

  • VERTICAL: portrait

model_asset_id

String

Virtual human model asset ID

model_asset_type

String

Virtual human model type.

  • HUMAN_MODEL_2D: virtual avatar

  • HUMAN_MODEL_3D: 3D virtual human

voice_config

VoiceConfig object

Voice configuration parameter.

video_config

VideoConfig object

Video output configuration.

scene_asset_id

String

Asset ID of a scene.

NOTE:

  • This parameter is not required for virtual avatar video production.

priv_data

String

Private data, which is entered by the user and then returned with the same content.

background_music_config

BackgroundMusicConfig object

Background music configuration.

review_config

ReviewConfig object

Content review configuration.

shoot_scripts

Array of ShootScriptShowItem objects

Video shooting scripts.

script_id

String

Script ID.

create_time

String

Creation time. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.

update_time

String

Update time. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.

audio_files

ShootScriptAudioFiles object

URLs for uploading audio files for speech control

script_cover_url

String

URL for downloading the script thumbnail.
Table 5 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 6 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 7 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 8 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.
Table 9 ReviewConfig

Parameter

Type

Description

no_need_review

Boolean

Content review whitelist. This feature is available only for users in the whitelist. The auto review policies apply to other users.
Table 10 ShootScriptShowItem

Parameter

Type

Description

sequence_no

Integer

Script No.

shoot_script

ShootScriptDetail object

Script configuration
Table 11 ShootScriptDetail

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.

thumbnail_url

String

Thumbnail URL of a script scene.
Table 12 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 13 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 14 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 15 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 16 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 17 ImageLayerConfig

Parameter

Type

Description

image_url

String

Image file URL.
Table 18 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 19 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 20 ShootScriptAudioFiles

Parameter

Type

Description

audio_file_url

Array of ShootScriptAudioFileItem objects

URLs for uploading audio files for speech control
Table 21 ShootScriptAudioFileItem

Parameter

Type

Description

sequence_no

Integer

Script No.

audio_file_upload_url

String

URL for uploading the audio file for speech control. It is returned when a script is created or updated. The maximum size of a single file is 100 MB. MP3/WAV/M4A files can be uploaded.

audio_file_download_url

String

URL for downloading the audio file for speech control. It is returned when script details are queried.

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/70b76xxxxxx34253880af501cdxxxxxx/digital-human-video-scripts/24bad716-87b1-45e5-8912-6102f7693265

Example Responses

Status code: 200

Succeeded.

{
  "script_name" : "The Legend of Nature",
  "script_description" : "Courseware",
  "model_asset_id" : "a5d295cdb345c11bd9f36bc22ced3a7a",
  "scene_asset_id" : "7ad01cf66f6cc54e45a2021558b7fbb0",
  "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" : "Hello, everyone. I'm Sara."
      },
      "animation_config" : [ {
        "animation" : "7affc1c9d10b9779957fce7d4aecbd35"
      } ],
      "background_config" : [ {
        "background_type" : "IMAGE",
        "background_config" : "978f893e1de4553c183b7a805e6290f5"
      } ]
    }
  } ]
}

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

Succeeded.

400

Parameters error, including the error code and its description.

401

Authentication is not performed or fails.

404

No content.

500

Internal service error.

Error Codes

See Error Codes.

Parent Topic: Video Script Management