API 操作の詳細 - - Alibaba Cloud ドキュメントセンター

このトピックでは、Web ソフトウェア開発キット (SDK) の API 操作について説明します。

API の概要

説明

以前の SDK バージョンには、非推奨のパラメーターとメソッドが含まれています。SDK を最新バージョンにアップグレードしてください。詳細については、「Web SDK の使用ガイド」をご参照ください。

クラス/プロトコル	API	説明
ARTCAICallEngine エンジン API 操作を定義します。	call	通話を開始します。
	handup	電話を切ります。説明ページの終了前 (たとえば、beforeunload イベントをリッスンすることによって) に handup を呼び出して通話を切断します。そうしない場合、エージェントは約 90 秒待機してから終了します。これにより、デジタルヒューマンの同時実行制限を超えるなどの問題が発生する可能性があります。
	setAgentView	エージェントのレンダリングビューを設定します。
	setLocalView	ローカルプレビュービューを設定します。
	interruptSpeaking	エージェントの発話を中断します。
	enableVoiceInterrupt	スマート割り込みを有効または無効にします。
	muteLocalCamera	カメラのプッシュを有効または無効にします。
	switchCamera	カメラを切り替えます。
	switchVoiceId	音声を切り替えます。
	mute	マイクをミュートまたはミュート解除します。
	muteAgentAudioPlaying	エージェントのオーディオストリームの再生を停止または再開します。
	startPushToTalk	プッシュツートークモードで話し始めます。
	finishPushToTalk	プッシュツートークモードでの発話を終了します。
	cancelPushToTalk	プッシュツートークモードで現在の発話をキャンセルします。
	enablePushToTalk	プッシュツートークモードを有効または無効にします。プッシュツートークモードでは、エージェントは finishPushToTalk が呼び出された後にのみ結果をレポートします。
	getRTCInstance	Alibaba Real-Time Communication (ARTC) エンジンを取得します。
	エージェントにテキストを送信する	エージェントにテキストメッセージを送信します。
	sendCustomMessageToServer	カスタムメッセージをサーバーに送信します。
	LLM システムプロンプトを更新する	大規模言語モデル (LLM) のシステムプロンプトを更新します。
	updateVcrConfig	VCR 設定を更新します。
	updateBailianAppParams	Model Studio アプリケーションのパラメーターを更新します。
	startVisionCustomCapture を開始する	視覚理解エージェントの場合、カスタムフレームキャプチャを開始します。これを開始すると、エージェントと音声で話すことはできません。
	カスタムキャプチャの停止	視覚理解エージェントの場合、カスタムフレームキャプチャを停止します。
	destroy	リソースを解放します。
ARTCAICallEngine エンジンコールバックイベント	errorOccurred	エラーが発生しました。
	callBegin	通話が開始されました。
	callEnd	通話が終了しました。
	agentStateChange	エージェントのステータスが変更されました。
	speakingVolumeChanged	ボリュームが変更されました。
	userSubtitleNotify	エージェントがユーザーの質問を認識した結果の通知。
	agentSubtitleNotify	エージェントの回答の通知。
	voiceIdChanged	現在の通話の音声が変更されました。
	pushToTalkChanged	プッシュツートークモードが変更されました。
	agentWillLeave	現在のエージェントが退出 (現在の通話を終了) しようとしています。
	receivedAgentCustomMessage	現在のエージェントからカスタムメッセージを受信しました。
	voiceInterruptChanged	現在の通話の音声割り込みが有効または無効になりました。
	humanTakeoverWillStart	ライブエージェントが現在のエージェントから引き継ごうとしています。
	humanTakeoverConnected	ライブエージェントの引き継ぎが接続されました。
	agentDataChannelAvailable	エージェントメッセージチャネルの可用性に関するコールバック。
	receivedAgentVcrResult	現在のエージェントから VCR 結果を受信しました。

API の詳細

ARTCAICallEngine の詳細

call

通話を開始します。

async call(userId: string, agentInfo: AICallAgentInfo, config?: AICallEngineConfig): Promise<void>>

パラメーター:

パラメーター	タイプ	説明
userId	String	現在のユーザーの UID。
agentInfo	AICallAgentInfo	エージェント情報。
config	AICallEngineConfig	初期化設定。型は次のように定義されます: { // マイクをミュートするかどうかを指定します。 muteMicrophone?: boolean; // ビジュアル理解モードでカメラをオフにするかどうかを指定します。 muteCamera?: boolean; // プッシュツートークを有効にするかどうかを指定します。 enablePushToTalk?: boolean; // ビジュアル理解モードのプレビュービデオ要素。 previewElement?: string \| HTMLVideoElement; // ビジュアル理解モードのカメラ設定。 cameraConfig?: AICallCameraConfig; }

handup

呼び出しを終了します。

async handup(): Promise<void>

setAgentView

エージェントのレンダリングビューを設定します。

setAgentView(view: HTMLVideoElement | string): void

パラメーター:

パラメーター	タイプ	説明
view	HTMLVideoElement \| string	video タグまたはその ID。

setLocalView

ローカルプレビュービューを設定します。

setLocalView(view?: HTMLVideoElement | string): void

パラメーター:

パラメーター	タイプ	説明
view	HTMLVideoElement \| string	video タグまたはその ID。このパラメーターを渡さない場合、プレビューは停止します。

interruptSpeaking

エージェントの発話を中断します。

async interruptSpeaking(): Promise<void>

enableVoiceInterrupt

スマート割り込みを有効または無効にします。

async enableVoiceInterrupt(enable: boolean): Promise<void>

パラメーター:

パラメーター	タイプ	説明
enable	boolean	この機能を有効または無効にします。

muteLocalCamera

ローカルカメラストリームの送信を有効または無効にします。

async muteLocalCamera(mute: boolean)

パラメーター:

パラメーター	タイプ	説明
mute	boolean	カメラをミュートするかどうかを指定します。

switchCamera

カメラを切り替えます。

async switchCamera(deviceId?: string)

パラメーター:

パラメーター	タイプ	説明
deviceId	string	デバイス ID。ID は ARTCAICallEngine.getCameraList() を呼び出すことで取得できます。モバイルデバイスでこのパラメーターを渡さない場合、システムはフロントカメラとリアカメラを切り替えます。

switchVoiceId

音声を切り替えます。

async switchVoiceId(voiceId: string): Promise<void>

パラメーター:

パラメーター	タイプ	説明
voiceId	string	音声 ID。

mute

マイクをミュートまたはミュート解除します。

async mute(mute: boolean): Promise<void>

パラメーター:

パラメーター	タイプ	説明
mute	boolean	マイクをミュートまたはミュート解除します。

muteAgentAudioPlaying

エージェントのオーディオストリームの再生を停止または再開します。

muteAgentAudioPlaying(mute: boolean)

パラメーター:

パラメーター	タイプ	説明
mute	boolean	オーディオをミュートするかどうかを指定します。

startPushToTalk

プッシュツートークモードで、発話を開始します。

startPushToTalk() :boolean;

finishPushToTalk

プッシュツートークモードで、発話を終了します。

finishPushToTalk() :boolean;

cancelPushToTalk

プッシュツートークモードで、現在の発話をキャンセルします。

cancelPushToTalk() :boolean;

enablePushToTalk

プッシュツートークモードを有効または無効にします。このモードが有効な場合、エージェントは finishPushToTalk が呼び出された後にのみ認識結果を送信します。

enablePushToTalk(enable: boolean):boolean;

パラメーター:

パラメーター	タイプ	説明
enable	Bool	モードを無効または有効にします。

getRTCInstance

ARTC エンジンインスタンスを取得します。

getRTCInstance(): AliRtcEngine | undefined

sendTextToAgent

エージェントにショートメッセージを送信します。

sendTextToAgent(req: AICallSendTextToAgentRequest);

パラメーター:

パラメータ

タイプ

説明

req

AICallSendTextToAgentRequest

送信するメッセージ構造体です。

new AICallSendTextToAgentRequest(text)

sendCustomMessageToServer

カスタムメッセージをサーバーに送信します。このメソッドは、通話が接続された後に呼び出す必要があります。

sendCustomMessageToServer(msg: string)

パラメーター:

パラメーター	タイプ	説明
msg	string	送信するコンテンツ。

updateLlmSystemPrompt

大規模言語モデル (LLM) のシステムプロンプトを更新します。このメソッドは、通話が接続された後に呼び出す必要があります。

updateLlmSystemPrompt(prompt: string)

パラメーター:

パラメーター	タイプ	説明
prompt	文字列	プロンプト。

updateVcrConfig

VCR 設定を更新します。

 public updateVcrConfig(vcrConfig: AICallAgentVcrConfig)

パラメーター:

パラメーター	タイプ	説明
vcrConfig	AICallAgentVcrConfig	VCR 設定。

updateBailianAppParams

Model Studio アプリケーションのパラメーターを更新します。

public updateBailianAppParams(params: JSONObject)

パラメーター:

パラメーター	タイプ	説明
params	object	Model Studio アプリケーションのパラメーター。

startVisionCustomCapture

視覚理解エージェントの場合、このメソッドはカスタムフレームキャプチャを開始します。このメソッドが呼び出されると、エージェントとの音声対話は無効になります。このメソッドは、通話が接続された後に呼び出す必要があります。

startVisionCustomCapture(req: AICallVisionCustomCaptureRequest)

パラメーター:

パラメーター

タイプ

説明

req

AICallVisionCustomCaptureRequest

設定情報。

{
  /**
   * マルチモーダル大規模モデルへのリクエストのテキストパラメーター。
   */
  text?: string;

  /**
   * true に設定すると、単一のフレームがキャプチャされ、システムはすぐにカスタムフレームキャプチャ状態を終了します。
   * false に設定すると、フレームは継続的にキャプチャされ、指定された期間が経過するとシステムはカスタムフレームキャプチャ状態を終了します。
   */
  isSingle?: boolean;

  /**
   * フレームキャプチャの間隔。
   * デフォルト: 5 秒。
   */
  eachDuration?: number;

  /**
   * 毎回キャプチャされる画像の数。
   * デフォルト: 2。
   */
  num?: number;

  /**
   * 連続フレームキャプチャの期間 (秒単位)。isSingle が true の場合、このパラメーターは無視されます。それ以外の場合、指定された期間に達すると、カスタムフレームキャプチャ状態は終了します。
   */
  duration?: number;

  /**
   * カスタムビジネス情報を含む JSON 文字列。この情報は、ビジネス処理のためにテキストおよび画像フレームとともに大規模モデルに送信されます。
   */
  userData?: string;
}

stopVisionCustomCapture

視覚理解エージェントの場合、カスタムフレームキャプチャを停止します。このメソッドは、通話が接続された後に呼び出す必要があります。

stopVisionCustomCapture()

destroy

リソースを解放します。

async destroy()

ARTCAICallEngine イベントの詳細

errorOccurred

通話中にエラーが発生したことを示します。

パラメーター:

パラメーター	タイプ	説明
code	AICallErrorCode	エラータイプ。

callBegin

通話が開始されたことを示します。

callEnd

通話が終了したことを示します。

agentStateChange

エージェントのステータスが変更されたことを示します。

パラメーター:

パラメーター	タイプ	説明
state	AICallAgentState	エージェントの現在のステータス: Listening、Thinking、または Speaking。

speakingVolumeChanged

発話音量の変化を示します。

パラメーター:

パラメーター	タイプ	説明
uid	string	発話者の UID。空の文字列は現在のユーザーを示します。
volume	Int32	ボリューム。範囲: 0～100。

userSubtitleNotify

ユーザーの入力に対するエージェントの音声認識結果を提供します。

パラメーター:

パラメーター	タイプ	説明
subtitle	AICallSubtitleData	字幕情報。

agentSubtitleNotify

エージェントの応答のテキストを提供します。

パラメーター:

パラメーター	タイプ	説明
subtitle	AICallSubtitleData	字幕情報。

voiceIdChanged

現在の通話の音声が変更されたことを示します。

パラメーター:

パラメーター	タイプ	説明
voiceId	string	現在の音声 ID。

pushToTalkChanged

プッシュツートークモードが変更されたことを示します。

パラメーター:

パラメーター	タイプ	説明
enable	boolean	モードが有効かどうかを指定します。

agentWillLeave

エージェントが通話を終了しようとしていることを示します。

パラメーター:

パラメーター	タイプ	説明
reason	number	退出理由: 2001 (アイドルタイムアウト) または 0 (その他)。
message	string	退出理由の説明。

receivedAgentCustomMessage

エージェントからカスタムメッセージを受信したことを示します。

パラメーター:

パラメーター	タイプ	説明
データ	オブジェクト	メッセージの内容。

voiceInterruptChanged

現在の通話の音声割り込みが有効または無効になったことを示します。

パラメーター:

パラメーター	タイプ	説明
enable	boolean	機能が有効かどうかを指定します。

humanTakeoverWillStart

ライブエージェントが通話を引き継ごうとしていることを示します。

パラメーター:

パラメーター	種類	説明
takeoverUid	文字列	ライブエージェントの UID。
テイクオーバーモード	数値	1: 出力はライブエージェントの音声を使用します。0: 出力はエージェントの音声を使用します。

humanTakeoverConnected

ライブエージェントが接続し、通話を引き継いだことを示します。

パラメーター:

パラメーター	タイプ	説明
takeoverUid	文字列	ライブエージェントの UID。

agentEmotionNotify

エージェントの感情分析結果を提供します。

パラメーター:

パラメーター	タイプ	説明
emotion	string	感情ラベル (neutral、happy、angry、sad など)。
userAsrSentenceId	number	ユーザーの質問に対する回答の文 ID。

agentDataChannelAvailable

このコールバックは、エージェントメッセージチャネルが利用可能になったときにトリガーされます。このコールバックがトリガーされた後、エージェントへのメッセージの送信を開始できます。

receivedAgentVcrResult

エージェントから VCR 結果を受信したことを示します。詳細については、「AICallAgentVcrResult」をご参照ください。

receivedAgentVcrResult: (result: AICallAgentVcrResult) => void;

パラメーター:

パラメーター	タイプ	説明
result	AICallAgentVcrResult	VCR の結果。