Help Center/ MetaStudio/ API Reference/ Intelligent Interaction/ Intelligent Interaction Management/ Virtual Avatar Dialog Task Management/ Querying a Virtual Avatar Intelligent Interaction Task

Updated on 2025-12-08 GMT+08:00

Online Debugging

CLI Examples

View PDF

Querying a Virtual Avatar Intelligent Interaction Task

Function

Queries a virtual avatar intelligent interaction task.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

URI

GET /v1/{project_id}/digital-human-chat/smart-chat-rooms/{room_id}/smart-chat-jobs/{job_id}/state

**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.
room_id	Yes	String	Interactive dialog ID. For details about how to obtain the ID, see Creating an Interactive Dialog.
job_id	Yes	String	Task 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 a request is sent. This parameter is mandatory for AK/SK authentication.
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
job_id	String	Interactive dialog task ID.
state	String	Interactive dialog task status. WAITING: The task is waiting for execution. PROCESSING: The task is being executed. SUCCEED: The task has been completed. FAILED: Task execution failed. DELETING: The task is being deleted.
duration	Float	Interactive dialog duration, in seconds. Value range: 0~2147483647
start_time	String	Start time of an interactive dialog task. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.
end_time	String	End time of an interactive dialog task. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.
error_info	ErrorResponse object	Error information of an interactive dialog task.
create_time	String	Creation time of an interactive dialog task. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.
lastupdate_time	String	Last update time of an interactive dialog task. The format complies with RFC 3339, for example, 2021-01-10T08:43:17Z.
chat_subtitle_config	SmartChatSubtitleConfig object	Dialog subtitle configuration
video_config	SmartChatVideoConfig object	Video output configuration.
voice_config_list	Array of SmartChatVoiceConfig objects	Voice configuration parameter list.
chat_video_type	String	Interactive dialog device. COMPUTER: PC MOBILE: mobile phone Hub: large screen
is_transparent	Boolean	Whether the background is transparent. Default value: false
default_language	String	Default language, which is used by the intelligent interaction APIs. Default value: CN CN: Chinese EN: English ESP: Spanish (supported only outside China) por: Portuguese (supported only outside China) Arabic: Arabic (supported only outside China) Thai: Thai (supported only outside China) Default value: CN
client_id	String	clientId
is_pool_mode	Boolean	Whether the resource pool mode is used. Default value: false
job_finish_reason	String	Reason for ending a dialog. NORMAL: The task ends normally. MUTE_TIMEOUT: The task ends because the request for muting timed out.
rtc_room_info	RTCRoomInfoList object	RTC room information.
chat_state	Integer	Interactive dialog status. 0: waiting for establishing a connection 1: waiting for disabling a connection 2: connection established 3: hibernated 4: waiting for hibernation Value range: 0~32
language	String	Language for intelligent interaction. Options: zh_CN: Simplified Chinese (discontinued. Use CN.) en_US: English (discontinued. Use EN.) CN: Chinese EN: English ESP: Spanish (supported only outside China) por: Portuguese (supported only outside China) Arabic: Arabic (supported only outside China) Thai: Thai (supported only outside China)
chat_access_address	String	Intelligent interaction access address.
chat_access_rest_address	String	Access address of the intelligent interaction REST API.

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

**Table 6** SmartChatSubtitleConfig
Parameter	Type	Description
dx	Integer	Coordinates of the pixel in the upper left corner of the subtitle box. NOTE: The video resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16). Value range: 0~1920
dy	Integer	Coordinates of the pixel in the upper left corner of the subtitle box. NOTE: The video resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16). Value range: 0~1920
width	Integer	Width (in pixels) of the image overlay (relative to the preview area size). NOTE: The preview area resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16). Value range: 1~7680
height	Integer	Height (in pixels) of the image overlay (relative to the preview area size). NOTE: The preview area resolution is 1920 x 1080 in landscape mode (16:9) and 1080 x 1920 in portrait mode (9:16). Value range: 1~7680

**Table 7** SmartChatVideoConfig
Parameter	Type	Description
width	Integer	Video width. Unit: pixel The value ranges from 320 to 2560. 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 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. Currently, only 1080 x 1920 is supported for virtual avatar livestreaming. Value range: 0~3840
height	Integer	Video height. Unit: pixel The value ranges from 320 to 2560. 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. Value range: 0~3840

**Table 8** SmartChatVoiceConfig
Parameter	Type	Description
voice_asset_id	String	Speech synthesis feature string
speed	Integer	Speaking speed. The value ranges from 50 to 200 and defaults to 100. The value 100 indicates the normal speaking speed of an adult, which is about 250 words per minute. Value range: 50~200 Default value: 100
pitch	Integer	Pitch. The value ranges from 50 to 200 and defaults to 100. Value range: 50~200 Default value: 100
volume	Integer	Volume. The value ranges from 90 to 240 and defaults to 140. Value range: 90~240 Default value: 140
provider	String	Third-party TTS vendor. Options: XIMALAYA: Himalaya TTS HUAWEI_EI: EI TTS MOBVOI: Mobvoi TTS
language	String	Language type. Default value: CN CN: Chinese EN: English ESP: Spanish (supported only outside China) por: Portuguese (supported only outside China) Arabic: Arabic (supported only outside China) Thai: Thai (supported only outside China) Default value: CN
language_desc	String	Language description.

**Table 9** RTCRoomInfoList
Parameter	Type	Description
app_id	String	RTC application ID.
room_id	String	RTC room ID.
users	Array of RTCUserInfo objects	Information about users joining an RTC room.

**Table 10** RTCUserInfo
Parameter	Type	Description
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

Status code: 400

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

Example Requests

GET https://metastudio.cn-north-4.myhuaweicloud.com/v1/70b76xxxxxx34253880af501cdxxxxxx/digital-human-chat/smart-chat-rooms/41c86xxxxxx34253850af102cdxxxxxx/smart-chat-jobs/38ch6xxxxxx5z233850af709crxxxxxx/state

Example Responses

Status code: 200

Returned when the request succeeded.

{
  "job_id" : "38ch6xxxxxx5z233850af709crxxxxxx",
  "state" : "WAITING",
  "start_time" : "2023-01-18T16:29:36Z",
  "end_time" : "2023-01-18T16:30:36Z",
  "duration" : 60,
  "rtc_room_info" : {
    "app_id" : "8cb83827a73d4d4f8191eae56bfea550",
    "room_id" : "41c86xxxxxx34253850af102cdxxxxxx",
    "users" : [ {
      "user_type" : "PLAYER",
      "user_id" : "eca4e308c4ed49f0b3822e5de33b34b6",
      "signature" : "83090ff53f3040xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxf4cb21585b781",
      "ctime" : 1702866202
    } ]
  },
  "chat_subtitle_config" : {
    "dx" : 256,
    "dy" : 256,
    "width" : 256,
    "height" : 256
  },
  "video_config" : {
    "width" : 1920,
    "height" : 1080
  },
  "chat_state" : 0,
  "chat_access_address" : "Domain:443"
}

Status code: 400

Parameters error, including the error code and its description.

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

Status Codes

Status Code	Description
200	Returned when the request succeeded.
400	Parameters error, including the error code and its description.

Error Codes

See Error Codes.

Parent Topic: Virtual Avatar Dialog Task Management

Previous topic: Ending a Virtual Avatar Intelligent Interaction Task

Next topic: Virtual Avatar Application Management

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