更新时间:2025-08-26 GMT+08:00
分享

主入口(HwICSUiSdk)

本节介绍Web SDK的接口详情。

表1 接口

接口

描述

三方驱动场景(是否支持)

非三方驱动场景(是否支持)

activeInteractionMode

获取当前生效的交互模式(语音问答/文本问答)。

×

addEventListeners

回调注册。

changeLanguage

设置交互任务语言。

×

checkBrowserSupport

检查浏览器是否支持。

create

创建交互任务。

destroy

销毁交互任务。

getJobInfo

获取交互任务信息。

getLanguageInfo

获取交互任务多语言信息。

×

initResourcePath

初始化语音唤醒资源,不使用语音唤醒能力则忽略该接口。

×

interactionModeSwitch

切换交互模式(语音问答/文本问答)。

×

interruptSpeaking

中断数字人讲话。

×

muteRemoteAudio

数字人静音。

playRemoteVideo

播放数字人音视频。

sendDrivenText

发送智能交互数字人主动播报的文本信息。

×

sendTextQuestion

发送问题文本。

×

setConfig

更新配置项。

setLogLevel

设置日志级别。

setThirdPartyConfig

设置第三方配置。

×

startChat

开始对话。

×

startStreamRecord

开始录制用户讲话声音。

×

startUserSpeak

用户开始提问。

×

stopChat

结束对话。

×

stopStreamRecord

结束录制用户讲话声音,并弹框提示或自动保存pcm格式录音文件。

×

stopUserSpeak

用户停止提问(注:此处只是停止ASR接收用户语音,对话仍处于激活态)。

×

unmuteRemoteAudio

数字人取消静音。

sendCustomLocalAudio

发送自定义音频数据

activeInteractionMode

(static) activeInteractionMode(): Promise<InteractionModeResult>

功能说明

获取当前生效的交互模式(语音问答/文本问答)。

请求参数

无。

返回参数

表2 InteractionModeResult

参数

类型

描述

result

boolean

执行结果。

errorCode

string | undefined

错误码,详细见表1

errorMsg

string | undefined

错误信息。

interactionMode

'AUDIO' | 'TEXT'

交互模式。

代码示例

const { result, interactionMode } = await HwICSUiSdk.activeInteractionMode();

addEventListeners

(static) addEventListeners(eventMap: EventMap): void

功能说明

设置事件回调。

请求参数

表3 eventMap

参数

是否必须

默认值

类型

描述

eventMap

-

EventMap

事件注册Map,请参见表4

表4 EventMap

参数

是否必须

默认值

类型

描述

error

-

(icsError: IcsError) => any

错误事件。

jobInfoChange

-

(jobInfo: JobInfo) => any

交互任务信息变更事件。

speakingStart

-

() => any

数字人开始讲话事件。

speakingStop

-

() => any

数字人结束讲话事件。

speechRecognized

-

(question: SpeechRecognitionInfo) => any

语音识别结果。

semanticRecognized

-

(answer: SemanticRecognitionInfo) => any

语义识别结果。

enterActive

-

() => any

数字人激活事件。

enterSleep

-

() => any

数字人自动休眠事件。

返回参数

代码示例

HwICSUiSdk.addEventListeners({
  error: (icsError) => {
    console.error('icsError', icsError);
  },
  jobInfoChange: (jobInfo) => {
    console.info('jobInfoChange', jobInfo);
  } 
});

changeLanguage

(static) changeLanguage(param: ChangeParam): Promise<void>

功能说明

设置交互任务语言。

请求参数

表5 param

参数

是否必选

默认值

类型

描述

param

-

ChangeParam

语言选项,请参见表6

表6 ChangeParam

参数

是否必选

默认值

类型

描述

langCode

-

'zh_CN' | 'en_US'

语言码,从接口getLanguageInfo中获取。

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.changeLanguage({
  langCode: 'zh_CN',
});

checkBrowserSupport

(static) checkBrowserSupport(): Promise<boolean>

功能说明

检查当前浏览器是否支持运行SDK。

请求参数

返回参数

Promise<boolean>:当前浏览器是否支持运行SDK。

代码示例

1
2
3
4
5
6
const result = await HwICSUiSdk.checkBrowserSupport();
if (result) {
  // 支持
} else {
  // 不支持
}

create

(static) create(param: CreateParam): Promise<void>

功能说明

通过获取的任务链接和一次性鉴权码,创建智能交互任务。

请求参数

表7 param

参数

是否必选

默认值

类型

描述

param

-

CreateParam

创建活动选项,请参见表8

表8 CreateParam

参数

是否必选

默认值

类型

描述

onceCode

-

string

一次性鉴权码,获取方式请参见创建一次性鉴权码

须知:CreateOnceCode接口需要在后台调用,不能在浏览器直接调用,否则有跨域问题。

serverAddress

-

string

智能交互服务端地址。

不同Region的取值如下所示:

  • 华北-北京四:metastudio-api.cn-north-4.myhuaweicloud.com
  • 华东-上海一:metastudio-api.cn-east-3.myhuaweicloud.com

robotId

-

string

智能交互活动ID,为参数“taskUrl”取值URL中携带的robot_id参数的值。

示例,如果URL为“https://metastudio-api.cn-north-4.myhuaweicloud.com/icswebclient?robot_id=a1b2c3d4e5f6”,则robotId值为a1b2c3d4e5f6

注意:robotId和taskUrl必须至少设置一个参数。

taskUrl

-

string

在MetaStudio控制台创建生成的数字人互动任务页面URL。URL获取方式,请参见创建智能交互数字人

注意:robotId和taskUrl必须至少设置一个参数。

containerId

-

string

渲染SDK交互界面UI的DOM节点ID。

config

-

ConfigMap

配置信息,请参见表18

eventListeners

-

EventMap

事件注册Map,请参见表4

第三方驱动的智能交互场景,必须传本参数。

logLevel

info

string

日志级别。

取值如下所示:

  • debug
  • info
  • warn
  • error
  • none

extendParamStr

''

string

扩展参数,按照Json字符串格式携带。比如:

'{"client_id":"2134","city":"city","enable_intent_interrupt":"1","extra_json_param":"{\\"param1\\":\\"value1\\",\\"param2\\":\\"value2\\"}"}'

返回参数

代码示例

HwICSUiSdk.create({
  serverAddress: 'serverAddress',
  onceCode: 'onceCode',
  robotId: 'robotId',
  containerId: 'ics-root',
  logLevel: 'debug',
  config: {
    enableCaption: true,
    enableChatBtn: false
  },
  eventListeners: {
    error: (error) => {
      console.error('sdk error', {
        message: error.message,
        code: error.code,
      }, error);
    }
  }
});

destroy

(static) destroy(): Promise<void>

功能说明

销毁交互任务。

请求参数

返回参数

代码示例

HwICSUiSdk.destroy();

getJobInfo

(static) getJobInfo(): Promise<JobInfo>

功能说明

获取交互任务信息。

请求参数

返回参数

表9 JobInfo

参数

类型

描述

jobId

string

任务ID。

websocketAddr

string | undefined

智能交互服务端websocket地址,三方驱动场景用来拼接websocket链接。

参数返回的地址默认无wss://前缀,实际使用时,需要补齐前缀。示例:如果返回字段内容为“Domain:443”,则需要拼接为wss://Domain:443。

代码示例

const jobInfo = await HwICSUiSdk.getJobInfo();

getLanguageInfo

(static) getLanguageInfo(): Promise<LanguageResult>

功能说明

获取交互任务多语言信息。如需实现多语言能力,需要在后台创建智能交互活动页面,配置多种语言,目前支持中文和英文两种语言。

请求参数

返回参数

表10 LanguageResult

参数

类型

描述

languageList

LanguageInfo[]

语言列表。

currentLanguage

'zh_CN' | 'en_US'

当前交互任务语言值。

result

boolean

执行结果。

errorCode

string | undefined

错误码,详细见表1

errorMsg

string | undefined

错误信息。

表11 LanguageInfo

参数

类型

描述

language

'zh_CN' | 'en_US'

语言。

language_desc

string

语言描述。

isDefault

boolean

是否为默认语言。

代码示例

const languageResult = await HwICSUiSdk.getLanguageInfo();

initResourcePath

(static) initResourcePath(param: ResourcePath): Promise<void>

功能说明

初始化语音唤醒资源,不使用语音唤醒能力则忽略该接口。

  • 3.0.1版本之后的websdk包中有如下两个资源文件,如果不使用语音唤醒,可忽略这两个文件。
    • wasmData.js:语音唤醒的算法资源文件。
    • modelData.js:语音唤醒的模型资源文件。
  • 4.0.0版本及之后的websdk支持worker线程开启语音唤醒能力,可通过useWorker参数启用。
  • SDK内置默认唤醒模型,支持定制唤醒词,并更新本地模型,详见Web语音唤醒

请求参数

表12 ResourcePath

参数

是否必选

默认值

类型

描述

wasmPath

'wasmData.js'

string

唤醒算法资源文件的相对路径或者绝对路径。

  • 相对路径为基于当前页面的路径,比如:页面地址为https://.../a/b,默认值为'wasmData.js',则算法可执行文件路径为https://.../a/b/wasmData.js。

    需要确保该路径为websdk包内部wasmData.js文件。

  • 绝对路径为完整的HTTP文件资源路径。

须知:如果useWorker设置为true,则需要传入绝对路径。

dataPath

'modelData.js'

string

唤醒模型资源文件的相对路径或者绝对路径。

  • 相对路径为基于当前页面的路径,比如:页面地址为https://.../a/b,默认值为'modelData.js',则算法可执行文件路径为https://.../a/b/modelData.js。
  • 绝对路径为完整的HTTP文件资源路径。

须知:如果useWorker设置为true,则需要传入绝对路径。

initModel

true

boolean

是否直接初始化唤醒模型。

初始化唤醒模型需要2~3s的加载时间,这段时间无法进行其他操作,所以需要根据实际情况选择模型初始化的时间点,详细说明如下所示:

  • 如果为true,会在接口执行时,初始化模型。
  • 如果为false,会在数字人创建过程中,初始化模型。

useWorker

false

boolean

是否开启语音唤醒worker线程能力。

  • 如果设置为true,则会启用worker线程加载语音唤醒算法,减少语音唤醒对渲染线程的性能影响。
  • 如果设置为false,则跟原流程保持一致,仍然使用渲染线程加载语音唤醒算法。

须知:如果开启此开关,参数wasmPath、dataPath均需传入绝对路径,不支持传入相对路径。

返回参数

无。

代码示例

await HwICSUiSdk.initResourcePath({
  wasmPath: 'wasmData.js',
  dataPath: 'modelData.js',
  initModel: true,
});

注意:如果未设置wasmPath和dataPath或设置的不对,会报类似下面的异常。

此时语音唤醒是无法正常使用的,需要将路径设置为正确的才行。

图1 异常报错

interactionModeSwitch

(static) interactionModeSwitch(param: InteractionModeParam): Promise<InteractionModeResult>

功能说明

切换交互模式(语音问答/文本问答)。

请求参数

表13 InteractionModeParam

参数

是否必须

默认值

类型

描述

interactionMode

AUDIO

  • AUDIO
  • TEXT

交互模式,语音交互还是文本交互。

返回参数

见:表2

代码示例

const { result } = await HwICSUiSdk.interactionModeSwitch({ interactionMode: 'AUDIO' });

interruptSpeaking

(static) interruptSpeaking(): Promise<UISdkResult>

功能说明

中断数字人讲话。

请求参数

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.interruptSpeaking();

muteRemoteAudio

(static) muteRemoteAudio(): Promise<boolean>

功能说明

数字人静音。

请求参数

返回参数

Promise<boolean>:数字人静音是否成功。

代码示例

const result = await HwICSUiSdk.muteRemoteAudio();

playRemoteVideo

(static) playRemoteVideo(): Promise<UISdkResult>

功能说明

播放数字人音视频。跟开关参数“autoPlayRemoteVideo”配合使用,当create接口中参数config的autoPlayRemoteVideo属性设置为false,则需要调用该接口主动播放数字人音视频。

请求参数

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.playRemoteVideo();

sendDrivenText

(static) sendDrivenText(param: TextDrivenParam): Promise<ChatResult>

功能说明

发送智能交互数字人主动播报的文本信息。

注意:主动播报结束时的最后一次调用,一定要传“isLast:true”参数,否则数字人讲话结束时无法及时收到speakingStop通知。

请求参数

表14 TextDrivenParam

参数

是否必须

默认值

类型

描述

text

""

string

智能交互数字人主动播报的文本信息。

isLast

false

boolean

是否是最后一条。

返回参数

请参见表25

代码示例

const { result } = await HwICSUiSdk.sendDrivenText({ text: '你好', isLast: true });

sendTextQuestion

(static) sendTextQuestion(param: TextQuestionParam): Promise<TextQuestionResult>

功能说明

发送问题文本。

请求参数

表15 TextQuestionParam

参数

是否必须

默认值

类型

描述

text

-

string

问题文本。

questionParam

-

string

文本提问时携带的自定义参数。

返回参数

表16 TextQuestionResult

参数

类型

描述

result

boolean

执行结果。

errorCode

string | undefined

错误码,详细见表1

errorMsg

string | undefined

错误信息。

chatId

string

对话id。

代码示例

const { result } = await HwICSUiSdk.sendTextQuestion({ text: '你是谁' });

setConfig

(static) setConfig(config: ConfigMap): void

功能说明

设置配置项,用于控制是否显示字幕或交互按钮。

请求参数

表17 config

参数

是否必须

默认值

类型

描述

config

-

ConfigMap

配置信息,请参见表18

表18 ConfigMap

参数

是否必须

默认值

类型

描述

enableCaption

false

boolean

是否显示字幕。

enableChatBtn

false

boolean

是否显示交互按钮。

enableHotIssues

false

boolean

是否显示热点问题。

enableWeakErrorInfo

true

boolean

是否显示弱提示。

示例:SDK内部websocket异常提示。

enableBusinessTrack

true

boolean

是否上报SDK埋点数据。

enableJobCache

true

boolean

是否启用任务缓存。如果用户希望每次修改任务配置后能快速生效,可不启用缓存。

  • 启用任务缓存,可加快数字人的启动速度。
  • 关闭任务缓存,每次调用create创建任务时,都会创建新任务,不使用上次缓存的任务。

useDefaultBackground

true

boolean

是否使用默认背景图。

enableLocalWakeup

false

boolean

是否启用语音唤醒能力。如果启用,需要先调用initResourcePath接口初始化唤醒资源路径,再调用create接口创建数字人。否则可能会因为语音唤醒算法加载失败或模型加载失败,导致语音唤醒功能不可用。

firstCreateLocalStream

false

boolean

是否优先创建本地流。解决某些Android设备在听筒模式下,数字人播放声音小的问题。

enableMediaViewer

true

boolean

是否启用图片预览。支持鼠标单击默认对话列表中的图片,实现放大查看功能。

如无需该功能, 可设置为false关闭。

autoPlayRemoteVideo

true

boolean

是否自动播放数字人音视频。跟接口playRemoteVideo配套使用,当前参数设置为false后,可以自行控制数字人音视频播放的时机。

enableCollectAudioDemand

false

boolean

是否按需采集麦克风声音。

  • 如果开启,则语音模式下,数字人开始对话则拾音,结束对话或自动休眠时,则停止拾音。
  • 如果关闭,则语音模式下,首次开始对话启动拾音,不会再停止拾音。

开启相比关闭,拾音工作区间最小化。但是开启后,每次重新开始对话,需要重新拾音,会有一些时耗。

注:若使用语音唤醒能力,且开启当前开关时,会一直采集麦克风声音,则该开关不生效。

enableOriginCutAlgorithm

false

boolean

是否使用原来的透明背景模式。3.3.0版本优化了透明背景的算法,如果发现没之前版本的效果好,可以通过此开关设置使用原版本的透明背景算法,保持原有效果。

enableVerbatim

false

boolean

是否开启默认字幕逐字显示效果。该开关需要在enableCaption设置为true,即开启默认字幕时生效。

  • 如果该开关设置为true,则字幕中数字人的回复会一个一个字地显示,而不是一段一段显示。
  • 如果该开关设置为false,则字幕中数字人的回复会按照大模型返回,一段一段显示(流式)或全部显示(非流式)。

返回参数

代码示例

HwICSUiSdk.setConfig({
  enableCaption: true,
  enableChatBtn: false,
  enableHotIssues: false,
  enableWeakErrorInfo: true,
});

setLogLevel

(static) setLogLevel(logLevel: 'debug' | 'info' | 'warn' | 'error' | 'none'): void

功能说明

设置输出日志的级别。

请求参数

表19 logLevel

参数

是否必须

默认值

类型

描述

logLevel

info

  • debug
  • info
  • warn
  • error
  • none

日志级别。

返回参数

代码示例

HwICSUiSdk.setLogLevel('warn');

setThirdPartyConfig

(static) setThirdPartyConfig(param: ThirdPartyParam): Promise<void>

功能说明

设置第三方配置。支持通过配置接入声影降噪设备。声影降噪设备上的多模态app开启的前提下,可以通过该接口与多模态app建立websocket连接,进而实现人脸唤醒、定向拾音以及拾音降噪等增强能力。

声影降噪设备目前支持分体式和瓦力两种类型。

请求参数

表20 param

参数

是否必选

默认值

类型

描述

param

-

ThirdPartyParam

第三方配置,详见表21

表21 ThirdPartyParam

参数

是否必选

默认值

类型

描述

uHan

-

UHanParam

声影分体式降噪设备配置,请参见表22

uHanV2

-

UHanParam

声影瓦力降噪设备配置,请参见表22

customRecord

-

CustomRecordConfig

使用自定义音频输入,请参见表23进行设置,且需搭配sendCustomLocalAudio接口使用才能生效。

表22 UHanParam

参数

是否必选

默认值

类型

描述

origin

"wss://127.0.0.1:10001"

string

声影降噪设备websocket建链地址,格式为“wss://IP:Port”或“ws://IP:Port”。

须知:origin和host参数二选一配置即可,如果2个参数均配置,优先使用origin配置。origin是4.0.0版本新增,低于此版本不支持配置origin。

host

"127.0.0.1:10001"

string

声影降噪设备websocket建链地址,格式为“IP:Port”。

须知:origin和host参数二选一配置即可,如果2个参数均配置,优先使用origin配置。

enable

false

boolean

是否启用声影降噪设备。

sleepDelay

10000

number

与数字人对话的用户人脸休眠时延。单位:ms。

showVideoUi

false

boolean

是否显示与数字人对话的用户人脸画面。

表23 CustomRecordConfig

参数

是否必选

默认值

类型

描述

enable

false

boolean

是否启用自定义音频输入。

返回参数

代码示例
// 启用声影分体式降噪设备配置
await HwICSUiSdk.setThirdPartyConfig({
  uHan: {
    enable: true,
    showVideoUi: true,
    host: `127.0.0.1:10001`,
    sleepDelay: 10000, 
  },
});

// 启用自定义音频输入
await HwICSUiSdk.setThirdPartyConfig({
  customRecord: {
    enable: true
  },
});

startChat

(static) startChat(param?: ChatParam): Promise<ChatResult>

功能说明

开始对话。

请求参数

表24 ChatParam

参数

是否必须

默认值

类型

描述

interactionMode

AUDIO

  • AUDIO
  • TEXT

交互模式,语音交互还是文本交互。

wakeupType

""

string

开始对话的方式。仅做数字人运维使用,如果有不同场景触发开始对话,比如按钮点击、语音唤醒等,可以通过该字段区分下触发场景。

preCheckPermissions

true

boolean

是否进行麦克风权限校验。

  • 默认开启校验,此时部分设备上浏览器进行检验的耗时可能比较长。如果遇到此类问题,可以提前通过代码“navigator.mediaDevices.getUserMedia({ audio: true })”(如果能正常获取到MediaStream对象,说明有麦克风权限)检查麦克风权限,再关闭当前配置。
  • 如果关闭该开关,可以提升当前接口的响应速度。

返回参数

表25 ChatResult

参数

类型

描述

result

boolean

执行结果。

errorCode

string | undefined

错误码,详细见表1

errorMsg

string | undefined

错误信息。

chatId

string

对话id。

sessionId

string

此轮对话的唯一标识,用于关联对话上下文内容。

代码示例

const { result } = await HwICSUiSdk.startChat({ interactionMode: 'AUDIO' });

startSpeak

(static) startSpeak(): Promise<UISdkResult>

功能说明

开始说话(注:接口已重命名为startUserSpeak,请直接切换至新接口)。

请求参数

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.startSpeak();

startStreamRecord

(static) startStreamRecord(): Promise<void>

功能说明

开始录制用户讲话声音。

请求参数

返回参数

代码示例

await HwICSUiSdk.startStreamRecord();

startUserSpeak

(static) startUserSpeak(param?: Param): Promise<UISdkResult>

功能说明

用户开始提问。

请求参数

表26 Param

参数

是否必须

默认值

类型

描述

preCheckPermissions

true

boolean

是否进行麦克风权限校验。

  • 默认开启校验,此时部分设备上浏览器进行检验的耗时可能比较长。如果遇到此类问题,可以提前通过代码“navigator.mediaDevices.getUserMedia({ audio: true })”(如果能正常获取到MediaStream对象,说明有麦克风权限)检查麦克风权限,再关闭当前配置。
  • 如果关闭该开关,可以提升当前接口的响应速度。

返回参数

表27 UISdkResult

参数

类型

描述

result

boolean

执行结果。

errorCode

string | undefined

错误码,详细见表1

errorMsg

string | undefined

错误信息。

代码示例

const { result } = await HwICSUiSdk.startUserSpeak({ preCheckPermissions: false });

stopChat

(static) stopChat(): Promise<ChatResult>

功能说明

结束对话。

请求参数

返回参数

请参见表25

代码示例

const { result } = await HwICSUiSdk.stopChat();

stopSpeak

(static) stopSpeak(): Promise<UISdkResult>

功能说明

停止说话(注:接口已重命名为stopUserSpeak,请直接切换至新接口)。

请求参数

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.stopSpeak();

stopStreamRecord

(static) stopStreamRecord(): Promise<void>

功能说明

结束录制用户讲话声音,并弹框提示或自动保存pcm格式录音文件。

请求参数

返回参数

代码示例

await HwICSUiSdk.stopStreamRecord();

stopUserSpeak

(static) stopUserSpeak(): Promise<UISdkResult>

功能说明

用户停止提问(注:此处只是停止ASR接收用户语音,对话仍处于激活态)。

请求参数

返回参数

请参见表27

代码示例

const { result } = await HwICSUiSdk.stopUserSpeak();

unmuteRemoteAudio

(static) unmuteRemoteAudio(): Promise<boolean>

功能说明

数字人取消静音。

请求参数

返回参数

Promise<boolean>:数字人取消静音是否成功。

代码示例

const result = await HwICSUiSdk.unmuteRemoteAudio();

sendCustomLocalAudio

(static) sendCustomLocalAudio(audioData: AudioData): Promise<void>

功能说明

发送自定义音频数据。

请求参数】AudioData

参数

类型

描述

base64Data

string

base64格式的音频数据。

uint8Arr

Uint8Array

Uint8Array格式的音频数据。

返回参数

无。

代码示例
const result = await HwICSUiSdk.sendCustomLocalAudio(
  {
    base64Data: ''
  }
);

相关文档