Starting a Virtual Human Intelligent Livestreaming Task

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

room_id

Yes

String

Live room ID.

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.

video_config

No

VideoConfig object

Video output configuration.

play_policy

No

PlayPolicy object

Script playback policy.

output_urls

No

Array of strings

Details:

Address of the third-party livestreaming platform for RTMP video stream push.

Constraints:

N/A

Options:

Currently, only one RTMP stream output address is supported.

Default value:

N/A

stream_keys

No

Array of strings

Details:

Stream key of the third-party livestreaming platform for RTMP video stream push, which corresponds to the ingest URL.

Constraints:

N/A

Options:

Currently, only one RTMP stream output address is supported.

Default value:

N/A

interaction_callback_url

No

String

Details:

Interactive callback URL, including authentication information.

This parameter is mandatory when trigger.reply_mode is set to CALLBACK.

Constraints:

N/A

Options:

The value contains 0 to 2,048 characters.

Default value:

N/A

live_event_callback_config

No

LiveEventCallBackConfig object

Live event HTTPS callback notification configuration

rtc_callback_config

No

RTCLiveEventCallBackConfig object

RTC callback event configuration. Compatible processing. If the configuration is not carried, LIVE_PROGRESS is subscribed by default.

view_mode

No

String

Details:

Landscape or portrait mode.

Constraints:

You do not need to set this parameter. The value is determined by the resolution in video_config.

Options:

• LANDSCAPE: landscape

• VERTICAL: portrait

Default value:

VERTICAL

co_streamer_config

No

CoStreamerConfig object

Co-streamer configuration

job_run_config

No

LiveJobRunConfig object

Running configuration of a virtual avatar livestreaming task

clip_mode

No

String

Definition

Clipping mode of the output video.

Constraints

N/A

Range

• RESIZE: video scaling

• CROP: video cropping

Default value:

RESIZE

codec

No

String

Definition

Video encoding format and video file format.

Constraints

Only virtual avatar video production supports VP8 and QTRLE encoding. When QTRLE encoding is used, the number of characters for text-based control is less than 1,500, and the audio length for audio-based control is less than 5 minutes.

You can use QTRLE encoding only after being whitelisted.

Range

• H264: H.264 encoding, MP4 file output

• VP8: VP8 encoding, WebM file output

• QTRLE: QTRLE encoding, MOV file output

Default Value

H264

Default value:

H264

bitrate

Yes

Integer

Definition

Average output bitrate. Unit: kbit/s

Constraints

• Quality is prioritized for virtual avatar video production, which may exceed the preset bitrate.

• Bitrate range for virtual avatar video production: [1000, 8000].

Default Value

N/A

Value range:

40~30000

width

Yes

Integer

Definition

Video width. Unit: pixel

Constraints

• 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 is available 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.

• Virtual avatar livestreaming and intelligent interaction support only 1080 x 1920 and 1920 x 1080.

Default Value

N/A

Value range:

0~3840

height

Yes

Integer

Definition

Video height.

Unit: pixel

Constraints

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

• Virtual avatar livestreaming and intelligent interaction support only 1080 x 1920 and 1920 x 1080.

Default Value

N/A

Value range:

0~3840

frame_rate

No

String

Definition

Frame rate. Unit: FPS

Constraints

The virtual avatar video frame rate is fixed at 25 FPS.

Default value:

25

is_subtitle_enable

No

Boolean

Definition

Whether the output video is subtitled.

Constraints

Subtitles are not supported for virtual avatar livestreaming.

Range

• true: subtitling enabled

• false: subtitling disabled

Default value:

false

subtitle_config

No

SubtitleConfig object

Subtitle configuration.

dx

No

Integer

Definition

Horizontal coordinate of the pixel in the upper left corner of the cropped video.

Constraints

This parameter takes effect when clip_mode is set to CROP.

Default Value

N/A

Value range:

-1920~3840

dy

No

Integer

Definition

Vertical coordinate of the pixel in the upper left corner of the cropped video.

Constraints

This parameter takes effect when clip_mode is set to CROP.

Default Value

N/A

Value range:

-1920~3840

is_enable_super_resolution

No

Boolean

Definition

Whether super resolution is enabled for a video.

Constraints

This parameter is available only for virtual avatar video production.

Range

• true: enabled

• false: disabled

Default value:

false

is_end_at_first_frame

No

Boolean

Definition

Whether the end frame of a video is the same as the start frame. Set this parameter to true if multiple virtual avatar videos need to be seamlessly merged.

Constraints

This parameter is supported only for virtual avatar video production. This setting becomes invalid after an action tag is inserted during video production.

Range

• true: enabled

• false: disabled

Default value:

false

output_external_url

No

String

External URL to which a video file is uploaded.

is_vocabulary_config_enable

No

Boolean

Definition

Whether to apply the pronunciation configuration of the current tenant.

Constraints

This parameter is available only for virtual avatar video production.

Range

• true: enabled

• false: disabled

Default value:

true

dx

No

Integer

Definition

Coordinates of the pixel in the lower left corner of the subtitle box.

Constraints

N/A

Default Value

N/A

Value range:

0~1920

dy

No

Integer

Definition

Coordinates of the pixel in the lower left corner of the subtitle box.

Constraints

N/A

Default Value

N/A

Value range:

0~1920

h

No

Integer

Definition

Subtitle box height.

Constraints

The parameter h is used to facilitate the calculation of the coordinates in the upper left corner of the subtitle box. This parameter is not used in the background.

Value range:

0~1920

w

No

Integer

Definition

Subtitle box width.

Constraints

• 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. This parameter is not used in the background.

Value range:

0~1920

font_name

No

String

Definition

Font. For details about the supported fonts, see Supported Fonts.

Constraints

N/A

Range

The value can contain 0 to 64 characters.

Default value:

HarmonyOS_Sans_SC_Black

font_size

No

Integer

Definition

Font size. The interface value ranges from 0 to 120. The actual value range is 24 to 120. Use the actual value range.

Constraints

N/A

Value range:

0~120

Default value:

54

font_color

No

String

Definition

RGB color value of the subtitle font.

Constraints

None.

Range

The value has a fixed length and contains 0 to 7 characters.

Default value:

#FFFFFF

stroke_color

No

String

Definition

RGB color value of the subtitle font stroke.

Constraints

None.

Range

The value has a fixed length and contains 0 to 7 characters.

stroke_thickness

No

Float

Definition

Pixel value of the subtitle font stroke.

Constraints

None.

Range

0-50

Value range:

0~50

opacity

No

Float

Definition

Subtitle font opacity. 0 indicates 100/ %transparency and 1 indicates 100/ %opacity. The default value is 1.

Constraints

None.

Range

0-1

Value range:

0~1

Default value:

1

repeat_count

No

Integer

Details:

Number of times that a script is played repeatedly.

• –1: The playback is repeated until it is stopped manually.

• 0: It is played only once.

• n: It is played n + 1 times.

Constraints:

N/A

Value range:

-1~100

Default value:

0

auto_play_script

No

Boolean

Details:

Indicates whether to automatically play a script.

Constraints:

N/A

Options:

• true: The script is automatically played after the task is initialized.

• false: After the task is initialized, the script is not played until signal appears.

Default value:

true

play_mode

No

String

Details:

Virtual avatar control method.

Constraints:

N/A

Options:

TEXT: text control, that is, using TTS

AUDIO: speech control

NO_PRESET: no preset script, manual control

Default value:

TEXT

random_play_mode

No

String

Details:

Method of random script reading.

Constraints:

Random script reading starts from the second round of reading.

Options:

• NONE: Random script reading is disabled.

• SCENE: Random script reading based on scenes is enabled. Paragraphs in a scene are read in sequence.

• SCRIPT_ITEM: Random script reading based on paragraphs is enabled. Script of each scene is read in sequence.

• SCENE_AND_SCRIPT_ITEM: Script of both scenes and paragraphs is read randomly.

Default value:

SCRIPT_ITEM

need_independent_capture_client

No

Boolean

Definition:

Whether an independent data collection device is required. This parameter is used when the client playback is separated from the command.

Constraints:

N/A

Value range:

• true: RTC users CAPTURE and PLAYER are assigned.

• false: Only the RTC user PLAYER is assigned.

Default value:

false

live_exit_config

No

LiveExitConfig object

Livestreaming task exit configuration

is_rewrite_delay

No

Boolean

Definition:

Whether the dynamically edited script that is not played takes effect in the next round.

Constraints:

N/A

Value range:

• true: taking effect in the next round

• false: taking effect immediately

Default value:

false

Default value:

false

max_live_duration

No

Integer

Definition:

Maximum livestreaming duration, in hours.

If this parameter is set to n, the livestream stops n hours after the livestream starts.

The maximum value is 168 (one week). The value 0 indicates no limitation.

Constraints:

If the condition for stopping a livestream is set to stopping immediately, the livestream will continue running for a maximum of five minutes after an error occurs. For other conditions, the processing duration needs to be included.

Default value:

If this parameter is not specified, the duration is not limited.

Value range:

0~168

auto_stop_mode

No

String

Definition:

How a livestream automatically stops.

• FORCE_EXIT: force stops the livestream immediately

• SEGMENT_END: stops the livestream when the segment ends

• SCENE_END: stops the livestream when the scene ends

• SCRIPT_END: stops the livestream when the script ends

Constraints:

N/A

Default value:

If this parameter is not specified, the value FORCE_EXIT is used.

max_exception_waiting_duration

No

Integer

Definition:

The maximum duration the livestream will continue running after an error is detected. Unit: minute.

If this parameter is set to n, the livestream stops n minutes after an exception is detected.

The maximum value is 60 (one hour). The value 0 indicates no limitation.

Constraints:

N/A

Default value:

If this parameter is not specified, the default value (3 minutes) is used. The default value may be slightly adjusted according to the service running status.

Value range:

0~60

live_event_type_callback_url

No

String

Details:

Live event callback address, which is an HTTPS address.

Constraints:

N/A

Options:

The value contains 0 to 2,048 characters.

Default value:

N/A

auth_type

No

String

Details:

Authentication type.

Constraints:

N/A

Options:

• NONE: The URL contains authentication.

• MSS_A: In HMACSHA256 signature mode, the hwSecret and hwTime parameters are added to the URL.

• MSS_A_HEAD: In HMACSHA256 signature mode, the hwSecret and hwTime parameters are placed in Head.

• MEITUAN_DEFAULT: This parameter is used only for Meituan's API callback.

Value format: hwSecret=hmac_sha256(Key, URI (live_event_callback_url) + hwTime)&hwTime=hex(timestamp)

Value format: x-hw-mss-secret=hmac_sha256(Key, URI (live_event_callback_url) + hwTime)

x-hw-mss-time=hex(timestamp)

Default value:

NONE

key

No

String

Details:

Key.

Constraints:

N/A

Options:

The value contains 0 to 32 characters.

Default value:

N/A

callback_event_type

No

Array of strings

Details:

Live event types in callbacks.

Constraints:

N/A

Options:

Currently, only the following options are supported:

• SHOOT_SCRIPT_SWITCH: script paragraph switching event

• RTMP_STREAM_STATE_CHANGE: RTMP link change callback event

• REPLY_COMMAND_FINISH: Playback is complete.

The callback event structure is defined as follows:

• event_type: event type

• message: event description

  • The SHOOT_SCRIPT_SWITCH event callback is defined as follows:

    {
      "event_type":  "SHOOT_SCRIPT_SWITCH",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"scene_script_name\":\"Product 1\",\"shoot_script_sequence_no\":\"2\",\"shoot_script_title\":\"Paragraph 2\"}"
    }

  • The RTMP_STREAM_STATE_CHANGE callback is defined as follows:

    {
      "event_type":  "RTMP_STREAM_STATE_CHANGE",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"output_url\":\"rtmp://xxx/xx/xx\",\"stream_key\":\"xxxxx\",\"state\":\"CONNECTED\"}"
    }

    The value of state can be CONNECTING, CONNECTED, DISCONNECTED, RECONNECTING, or END.

  • The REPLY_COMMAND_FINISH callback is defined as follows:

    {
      "event_type":  "REPLY_COMMAND_FINISH",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"reply_id\":\"e87104f76d7546ce8a46ac6b04c49c3c"}"
    }

rtc_callback_event_type

No

Array of strings

Live event types in RTC callbacks.

Currently, only the following options are supported:

• LIVE_PROGRESS: live script progress notification

• REPLY_COMMAND_FINISH: Playback is complete.

The callback event structure is defined as follows:

• message_type: message type

• data: message description

  • The LIVE_PROGRESS event callback is defined as follows:

    {
        "message_type": "live_progress_notify",
        "data": {
            "script_name": "Scene 1",
            "shoot_script_sequence_no": 2,
            "shoot_script_title": "Greeting",
            "offset": "247",
            "reply_id": "e87104f76d7546ce8a46ac6b04c49c3c"
        }
    }

  • The REPLY_COMMAND_FINISH callback is defined as follows:

    {
      "message_type": "reply_command_finish_notify",
      "data":"{
        "reply_id":"e87104f76d7546ce8a46ac6b04c49c3c"
      }"
    }

voice_config

No

VoiceConfig object

Voice configuration parameter.

streamer_action

No

String

Details:

Behavior of the streamer when the co-streamer speaks.

Constraints:

N/A

Options:

• SILENCE: silent

• VOLUME_DOWN: decreased volume

Default value:

N/A

voice_asset_id

Yes

String

Definition

Timbre asset ID, which can be queried from the asset library.

For details about how to query voice IDs, see Querying Preset Voice IDs.

Constraints

N/A

Range

The value can contain 1 to 256 characters.

Default Value

N/A

speed

No

Integer

Definition

Speaking speed. 50 indicates 0.5x speaking speed, 100 indicates normal speaking speed, and 200 indicates 2x speaking speed.

The value 100 indicates the normal speaking speed of an adult, which is about 250 words per minute.

Constraints

N/A

Value range:

50~200

Default value:

100

pitch

No

Integer

Definition

Pitch.

Constraints

N/A

Value range:

50~200

Default value:

100

volume

No

Integer

Definition

Volume.

Constraints

N/A

Value range:

90~240

Default value:

140

allow_resource_type

No

String

Allowed resource type.

• PERIOD: yearly/monthly resources

• ONDEMAND: pay-per-use resources

• UNLIMITED: unlimited resource type

• ONE_TIME: one-off resources

Default value:

UNLIMITED

single_job_in_room

No

Boolean

Whether only one livestreaming task is allowed in a live room.

• true: Only one livestreaming task is allowed in a live room.

• false: The number of livestreaming tasks in a live room is not limited.

Default value:

false

X-Request-Id

String

Request ID.

job_id

String

Livestreaming task ID.

rtc_room_info

RTCRoomInfoList object

RTC room information.

live_event_report_url

String

URL for reporting livestreaming events. Users report their own livestreaming events to this URL to trigger intelligent interaction and automatic reply.

live_event_callback_config

LiveEventCallBackConfig object

Live event HTTPS callback notification configuration

live_warning_info

Array of LiveWarningItem objects

List of livestreaming risk alarms.

limit_duration

Integer

Definition:

Maximum livestreaming duration, in hours.

The value 0 indicates no limit.

Constraints:

If the condition for stopping a livestream is set to stopping immediately, the livestream will continue running for a maximum of five minutes after an error occurs. For other conditions, the processing duration needs to be included.

Default value:

If this parameter is not specified, the duration is not limited.

Value range:

0~168

app_id

String

RTC application ID.

room_id

String

RTC room ID.

users

Array of RTCUserInfo objects

Information about users joining an RTC room.

user_type

String

User type.

• CAPTURE: Live assistant, which pushes video streams captured by cameras to RTC rooms.

• ANIMATION: Visual control service, which pulls video streams from RTC rooms to generate motion data.

• RENDER: Rendering service, which renders motion data into virtual human animations.

• PLAYER: Common viewer, who can watch the original video stream or virtual human animation video stream.

• INFERENCE_USER: Virtual human inference user, who receives audio streams from and pushes video streams to an RTC room.

• END_USER: Device user, who receives video streams from and pushes audio streams to an RTC room.

user_id

String

RTC user ID.

signature

String

RTC authentication token.

ctime

Long

Validity period. Timestamp, in seconds.

Value range:

0~4294967295

live_event_type_callback_url

String

Details:

Live event callback address, which is an HTTPS address.

Constraints:

N/A

Options:

The value contains 0 to 2,048 characters.

Default value:

N/A

auth_type

String

Details:

Authentication type.

Constraints:

N/A

Options:

• NONE: The URL contains authentication.

• MSS_A: In HMACSHA256 signature mode, the hwSecret and hwTime parameters are added to the URL.

• MSS_A_HEAD: In HMACSHA256 signature mode, the hwSecret and hwTime parameters are placed in Head.

• MEITUAN_DEFAULT: This parameter is used only for Meituan's API callback.

Value format: hwSecret=hmac_sha256(Key, URI (live_event_callback_url) + hwTime)&hwTime=hex(timestamp)

Value format: x-hw-mss-secret=hmac_sha256(Key, URI (live_event_callback_url) + hwTime)

x-hw-mss-time=hex(timestamp)

Default value:

NONE

key

String

Details:

Key.

Constraints:

N/A

Options:

The value contains 0 to 32 characters.

Default value:

N/A

callback_event_type

Array of strings

Details:

Live event types in callbacks.

Constraints:

N/A

Options:

Currently, only the following options are supported:

• SHOOT_SCRIPT_SWITCH: script paragraph switching event

• RTMP_STREAM_STATE_CHANGE: RTMP link change callback event

• REPLY_COMMAND_FINISH: Playback is complete.

The callback event structure is defined as follows:

• event_type: event type

• message: event description

  • The SHOOT_SCRIPT_SWITCH event callback is defined as follows:

    {
      "event_type":  "SHOOT_SCRIPT_SWITCH",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"scene_script_name\":\"Product 1\",\"shoot_script_sequence_no\":\"2\",\"shoot_script_title\":\"Paragraph 2\"}"
    }

  • The RTMP_STREAM_STATE_CHANGE callback is defined as follows:

    {
      "event_type":  "RTMP_STREAM_STATE_CHANGE",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"output_url\":\"rtmp://xxx/xx/xx\",\"stream_key\":\"xxxxx\",\"state\":\"CONNECTED\"}"
    }

    The value of state can be CONNECTING, CONNECTED, DISCONNECTED, RECONNECTING, or END.

  • The REPLY_COMMAND_FINISH callback is defined as follows:

    {
      "event_type":  "REPLY_COMMAND_FINISH",
      "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"reply_id\":\"e87104f76d7546ce8a46ac6b04c49c3c"}"
    }

warning_type

String

Alarm type.

• TOO_LESSS_SCRIPT_ITEMS: There are too few paragraphs (scripts).

• TOO_SHORT_SCRIPT_TIME: The total duration of paragraphs (scripts) is too short.

• TOO_LESS_DANMAKU_RULES: There are too few on-screen comment interaction rules.

• RANDOM_PLAY_CLOSED: The random playback function is disabled.

• ROTATION_MODEL_CLOSED: Streamer rotation is not configured.

error_code

String

Error code.

error_msg

String

Error description.

error_code

String

Error code.

error_msg

String

Error description.

error_code

String

Error code.

error_msg

String

Error description.

202

Succeeded.

400

Parameters error, including the error code and its description.

401

Authentication is not performed or fails.

500

Internal service error.