Help Center/ MetaStudio/ API Reference/ Virtual Avatar Video Production/ Video Script Management/ Creating a Video Script

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

Online Debugging

CLI Examples

View PDF

Creating a Video Script

Function

Creates a video script.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/digital-human-video-scripts

**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_name	Yes	String	Script name.
script_description	No	String	Script description.
view_mode	No	String	Landscape or portrait mode. The default value is LANDSCAPE. LANDSCAPE: landscape VERTICAL: portrait
model_asset_id	No	String	Virtual human model asset ID
model_asset_type	No	String	Virtual human model type. HUMAN_MODEL_2D: virtual avatar HUMAN_MODEL_3D: 3D virtual human
voice_config	No	VoiceConfig object	Voice configuration parameter.
video_config	No	VideoConfig object	Video output configuration.
scene_asset_id	No	String	Asset ID of a scene. NOTE: This parameter is not required for virtual avatar video production.
priv_data	No	String	Private data, which is entered by the user and then returned with the same content.
background_music_config	No	BackgroundMusicConfig object	Background music configuration. NOTE: Background music can be set only for virtual avatar video production, but not for 3D virtual human video production.
review_config	No	ReviewConfig object	Content review configuration.
shoot_scripts	Yes	Array of ShootScriptItem objects	Video shooting scripts.

**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** 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 8** 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 9** ShootScriptItem
Parameter	Mandatory	Type	Description
sequence_no	No	Integer	Script No.
shoot_script	Yes	ShootScript object	Performance script.

**Table 10** 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 11** 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 12** 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 13** 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 14** 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 15** 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 16** ImageLayerConfig
Parameter	Mandatory	Type	Description
image_url	No	String	Image file URL.

**Table 17** 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 18** 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.

Response Parameters

Status code: 200

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

**Table 20** Response body parameters
Parameter	Type	Description
script_id	String	Script ID.
audio_files	ShootScriptAudioFiles object	URLs for uploading audio files for speech control

**Table 21** ShootScriptAudioFiles
Parameter	Type	Description
audio_file_url	Array of ShootScriptAudioFileItem objects	URLs for uploading audio files for speech control

**Table 22** 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 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/70b76xxxxxx34253880af501cdxxxxxx/digital-human-video-scripts

{
  "script_name" : "The Legend of Nature",
  "script_description" : "Courseware",
  "model_asset_id" : "a5d295cdb345c11bd9f36bc22ced3a7a",
  "scene_asset_id" : "7ad01cf66f6cc54e45a2021558b7fbb0",
  "voice_config" : {
    "voice_asset_id" : "a5d295cdb345c11bd9f36bc22ced3a7a"
  },
  "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"
      } ]
    }
  } ]
}

Example Responses

Status code: 200

Succeeded.

{
  "script_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	Succeeded.
400	Parameters error, including the error code and its description.
401	Authentication is not performed or fails.
500	Internal service error.

Error Codes

See Error Codes.

Parent Topic: Video Script Management

Previous topic: Video Script Management

Next topic: Querying Video Scripts

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot