文档首页/数字内容生产线 MetaStudio/API参考/智能交互/智能交互管理/智能交互数字人对话任务管理/启动数字人智能交互任务 - StartSmartChatJob
更新时间：2026-01-29 GMT+08:00
在线调试
CLI示例
查看PDF
分享

启动数字人智能交互任务 - StartSmartChatJob

功能介绍

该接口用于启动数字人智能交互任务。

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1/{project_id}/digital-human-chat/smart-chat-rooms/{room_id}/smart-chat-jobs

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，获取方法请参考获取项目ID。

room_id

是

String

智能交互对话ID，获取方法请参考创建智能交互对话直播间。

表2 Query参数

参数

是否必选

参数类型

描述

robot_id

是

String

应用ID，获取方法请参考创建应用。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

用户Token。使用Token鉴权方式时必选。

通过调用IAM服务获取用户Token接口获取。

响应消息头中X-Subject-Token的值。

Authorization

否

String

使用AK/SK方式认证时必选，携带的鉴权信息。

X-Sdk-Date

否

String

使用AK/SK方式认证时必选，请求的发生时间。

X-Project-Id

否

String

使用AK/SK方式认证时必选，携带项目ID信息。

X-App-UserId

否

String

第三方用户ID。不允许输入中文。

表4 请求Body参数

参数

是否必选

参数类型

描述

extend_param

否

String

扩展参数，按照Json格式携带。

  • city：所在城市

  • client_id：客户端ID

  • extra_json_param：自定义参数

响应参数

状态码：200

表5 响应Header参数

参数

参数类型

描述

X-Request-Id

String

请求ID。

表6 响应Body参数

参数

参数类型

描述

job_id

String

智能交互对话任务ID。

language

String

智能交互语言

  • zh_CN:简体中文

  • en_US:英语

rtc_room_info

RTCRoomInfoList object

RTC房间信息。

chat_subtitle_config

SmartChatSubtitleConfig object

对话字幕配置

video_config

SmartChatVideoConfig object

视频输出配置。

voice_config_list

Array of SmartChatVoiceConfig objects

语音配置参数列表。

chat_video_type

String

智能交互对话端配置。

  • COMPUTER: 电脑端

  • MOBILE: 手机端

  • HUB: 大屏

region

String

算力所在region。

  • cn-north-4: 北京4

  • cn-southwest-2: 贵阳1

chat_access_address

String

智能交互接入地址。

chat_access_rest_address

String

智能交互Rest接口接入地址。

is_transparent

Boolean

是否透明背景

默认取值：

false

default_language

String

默认语言，智能交互接口使用。默认值CN。

  • CN：中文。

  • EN：英文。

  • ESP：西班牙语（仅海外站点支持）

  • por：葡萄牙语（仅海外站点支持）

  • Arabic：阿拉伯语（仅海外站点支持）

  • Thai：泰语（仅海外站点支持）

  • fr：法语（仅海外站点支持）

默认取值：

CN

表7 RTCRoomInfoList

参数

参数类型

描述

app_id

String

RTC应用ID。

room_id

String

RTC房间ID。

users

Array of RTCUserInfo objects

加入RTC房间用户信息。

表8 RTCUserInfo

参数

参数类型

描述

user_type

String

用户类型。

  • CAPTURE: 直播助手，将摄像头获取视频流推送到RTC房间

  • ANIMATION: VDS服务，从RTC房间拉视频流生成动作数据

  • RENDER: 渲染服务，将动作数据渲染成数字人动画

  • PLAYER: 普通观看方，可选择原始视频流或者数字人动画视频流观看

  • INFERENCE_USER: 数字人推理端用户。从RTC房间接收音频流，并推送视频流到RTC房间

  • END_USER: 端侧用户。从推送音频流到RTC房间，并从RTC房间接收视频流

user_id

String

RTC用户ID。

signature

String

RTC鉴权token。

ctime

Long

有效期。时间戳，单位：秒。

取值范围：

0~4294967295

表9 SmartChatSubtitleConfig

参数

参数类型

描述

dx

Integer

字幕左上角像素点坐标。

说明：
*横屏（16:9）视频像素为1920x1080；竖屏（9:16）视频像素为1080x1920。

取值范围：

0~1920

dy

Integer

字幕左上角像素点坐标。

说明：
*横屏（16:9）视频像素为1920x1080；竖屏（9:16）视频像素为1080x1920。

取值范围：

0~1920

width

Integer

图层图片宽度像素值（相对画布大小）。

说明：
横屏（16:9）画布像素为1920x1080；竖屏（9:16）画布像素为1080x1920。

取值范围：

1~7680

height

Integer

图层图片高度像素值（相对画布大小）。

说明：
横屏（16:9）画布像素为1920x1080；竖屏（9:16）画布像素为1080x1920。

取值范围：

1~7680

表10 SmartChatVideoConfig

参数

参数类型

描述

width

Integer

视频宽度。

单位：像素。

最小值320，最大值2560。

说明：

  • clip_mode=RESIZE时，当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率。4K分辨率视频需要分身数字人模型支持4K的情况下才能使用。

  • clip_mode=CROP，裁剪后视频，（dx,dy）为原点，保留视频像宽度为width。

  • 分身数字人直播目前只支持1080x1920。

取值范围：

0~3840

height

Integer

视频高度。

单位：像素。

最小值320，最大值2560。

说明：

  • clip_mode=RESIZE时，当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率分辨率。

  • clip_mode=CROP，裁剪后视频，（dx,dy）为原点，保留视频像高度为height。

  • 分身数字人直播目前只支持1080x1920。

取值范围：

0~3840

表11 SmartChatVoiceConfig

参数

参数类型

描述

voice_asset_id

String

语音合成特征字符串

speed

Integer

语速。默认值100，最小值50，最大值200。

说明：
当取值为“100”时，表示一个成年人正常的语速，约为250字/分钟。

取值范围：

50~200

默认取值：

100

pitch

Integer

音高。默认值100，最小值50，最大值200。

取值范围：

50~200

默认取值：

100

volume

Integer

音量。默认值140，最小值90，最大值240。

取值范围：

90~240

默认取值：

140

provider

String

第三方TTS供应商类型。

  • XIMALAYA：喜马拉雅TTS

  • HUAWEI_EI：EI TTS

  • MOBVOI：出门问问TTS

language

String

语言类型。默认值CN。

  • CN：中文。

  • EN：英文。

  • ESP：西班牙语（仅海外站点支持）

  • por：葡萄牙语（仅海外站点支持）

  • Arabic：阿拉伯语（仅海外站点支持）

  • Thai：泰语（仅海外站点支持）

  • fr：法语（仅海外站点支持）

默认取值：

CN

language_desc

String

语言描述。

状态码：400

表12 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

请求示例

POST https://metastudio.cn-north-4.myhuaweicloud.com/v1/70b76xxxxxx34253880af501cdxxxxxx/digital-human-chat/smart-chat-rooms/41c86xxxxxx34253850af102cdxxxxxx/smart-chat-jobs?robot_id=4d54xxxxxxc446249xxxxxxxxxx6526

响应示例

状态码：200

处理成功返回。

{
  "job_id" : "38ch6xxxxxx5z233850af709crxxxxxx",
  "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_access_address" : "Domain:443"
}

状态码：400

请求传参异常，包含错误码及对应描述。

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

状态码

状态码

描述

200

处理成功返回。

400

请求传参异常，包含错误码及对应描述。

错误码

请参见错误码。

父主题： 智能交互数字人对话任务管理