腾讯云智能数智人云渲染会话交互服务 API 概述

本文档主要描述 腾讯云智能数智人 交互aPaas 平台的开放接口协议，以及阐述接口的调用流程。
调用前须知
调用交互数智人服务接口前请确保您进行了形象采购以及购买了交互服务，详情请查看购买指南中的购买指引。
云渲染会话交互接入方案有两种对接形式，包括 API 接入方式 和 SDK 接入方式。云渲染场景的数字人形象需要通过云端引擎来驱动，所以必须购买的服务包括：在有效期内的形象、会话互动并发，如下图所示：
形象的来源有三种：
租赁我们已有的形象，该模式下需要在购买页购买“形象租赁”中选择形象进行下单，默认有效期1年。1年后需重新购买。
找我们定制形象，该模式下需要联系我们，进行专门的形象定制。会产生三笔费用：
定制费用，联系我们获取；
引擎费用，在购买页下单“云端驱动引擎”；
定制形象的续期费用，形象1年后会过期，需要在过期前下单“定制形象续期”对定制形象进行续费。
客户自己提供形象，该模式下需要联系我们，进行形象的对接，形式上也属于定制形象，但没有定制费用。会产生两笔费用：
引擎费用，在购买页下单“云端驱动引擎”；
形象续期费用，在过期前下单“定制形象续期”对形象进行续费。
会话交互：该交互用于构建多路实时会话，例如用户需要同时保持2路不相关的实时会话，则需要购买2路“会话互动并发数”。
﻿
接口调用环境
正式环境域名：
https://gw.tvs.qq.com
wss://gw.tvs.qq.com
接口调用方式
调用每个接口时需要在接口的 query 中传入公共参数及签名。参数及签名方式说明参考以下链接：
﻿数智人 aPaas 接口调用方式﻿
交互数智人 API 概览
功能类别
API 标题
﻿
﻿
接口
说明
会话管理
创建会话
﻿使用数智人平台项目创建会话﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/createsession
使用数智人平台项目创建会话，获取数智人画面的流播放地址。
﻿
﻿
﻿使用形象资产创建会话﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/createsessionbyasset
使用客户有权限的形象资产直接创建会话，获取数智人画面的流播放地址。用于未在数智人平台创建项目的情况。
﻿
﻿查询会话状态﻿
﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/statsession
查询指定会话的当前状态。
﻿
﻿开启会话﻿
﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/startsession
会话就绪之后，必须调用此口才可以进行驱动。
﻿
﻿关闭会话﻿
﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/closesession
关闭会话，停止数智人推流，释放并发。
﻿
查询会话列表
﻿查询 uin 下的会话列表﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofuin
用于查询某个uin账号所有进行中的会话列表。
﻿
﻿
﻿查询数智人项目下的会话列表﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofprojectid
用于查询数智人项目下的所有进行中的会话列表。
﻿
﻿
﻿查询个人资产形象下的会话列表﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofassetvk
用于查询个人资产形象下的所有进行中的会话列表。
数智人指令驱动
﻿
说明：
指令驱动适用场景参考驱动指令说明﻿
长连接驱动(WebSocket)
﻿
﻿创建长连接通道﻿
WSS /v2/ws/ivh/interactdriver/interactdriverservice/commandchannel
建立 websocket 长连接通道，上行发送驱动指令、接收下行消息。
﻿
﻿
﻿
﻿文本驱动指令（WebSocket）﻿
﻿
建立长连接通道后，可以通过 WebSocket 长连接发送文本驱动数智人。
﻿
﻿
﻿
﻿流式文本驱动指令（WebSocket）﻿
﻿
建立长连接通道后，可以通过 websocket 长连接发送流式文本驱动数智人。
﻿
﻿
﻿
﻿音频驱动指令（WebSocket）﻿
﻿
建立长连接通道后，可以通过 websocket 长连接发送音频驱动数智人。
﻿
﻿
﻿
﻿心跳指令（WebSocket）﻿
﻿
在超过10分钟后如果云端未收到任何驱动指令会自动断开连接并释放并发。创建长通道后，通过发送心跳指令，可对会话进行续期。发送间隔大于30s，小于10分钟
﻿
直接驱动(HTTPS)
﻿
﻿文本驱动指令（HTTP 短连接）﻿
POST /v2/ivh/interactdriver/interactdriverservice/command
HTTP方式发送文本驱动指令
说明：
不用建立长连接通道，常用于试用、一句话驱动等场景。
其他接口
﻿实时更新数智人画面参数﻿
﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/updatesessionconfig
用于实时更新视频流画面中的人物大小、位置、背景图。此接口不再建议使用，后续不再继续迭代新特性。
﻿
﻿获取进入 TRTC 房间秘钥﻿
﻿
﻿
POST /v2/ivh/sessionmanager/sessionmanagerservice/gettrtcsign
当创建直播会话时选择了 trtc 协议，除数字人之外的其他用户若需加入房间使用此接口获取该用户的入房秘钥。
接口接入流程
接入指引
通过下列步骤获取交互数智人服务：
1. 购买相关产品及服务：购买链接；
2. 创建会话：使用下列两种方式之一与云端创建会话，获取数智人视频流会话状态与流播放地址：
﻿使用数智人平台项目创建会话﻿
﻿使用形象资产创建会话﻿
3. 等待流就绪：当会话状态为准备中，代表数智人模型正在加载中，时长一般不会超过两分钟。通过调用查询会话状态接口循环查询，直到会话状态为进行中。会话状态状态码说明见查询会话状态；
4. 播放视频流；
5. 开启会话：视频流就绪后，需要调用开启会话接口，使数智人可以通过指令进行驱动；
6. 发送驱动指令：各种驱动指令说明及要求请参考驱动指令说明；
7. 关闭会话：交互完成后请关闭会话。
接入流程
﻿
﻿
﻿
﻿

功能类别	API 标题					接口	说明
会话管理	创建会话	使用数智人平台项目创建会话			POST /v2/ivh/sessionmanager/sessionmanagerservice/createsession	使用数智人平台项目创建会话，获取数智人画面的流播放地址。
	创建会话			使用形象资产创建会话			POST /v2/ivh/sessionmanager/sessionmanagerservice/createsessionbyasset	使用客户有权限的形象资产直接创建会话，获取数智人画面的流播放地址。用于未在数智人平台创建项目的情况。
		查询会话状态					POST /v2/ivh/sessionmanager/sessionmanagerservice/statsession	查询指定会话的当前状态。
		开启会话					POST /v2/ivh/sessionmanager/sessionmanagerservice/startsession	会话就绪之后，必须调用此口才可以进行驱动。
		关闭会话					POST /v2/ivh/sessionmanager/sessionmanagerservice/closesession	关闭会话，停止数智人推流，释放并发。
		查询会话列表	查询 uin 下的会话列表			POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofuin	用于查询某个uin账号所有进行中的会话列表。
				查询数智人项目下的会话列表			POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofprojectid	用于查询数智人项目下的所有进行中的会话列表。
				查询个人资产形象下的会话列表			POST /v2/ivh/sessionmanager/sessionmanagerservice/listsessionofassetvk	用于查询个人资产形象下的所有进行中的会话列表。
数智人指令驱动说明：指令驱动适用场景参考驱动指令说明	长连接驱动(WebSocket)			创建长连接通道	WSS /v2/ws/ivh/interactdriver/interactdriverservice/commandchannel	建立 websocket 长连接通道，上行发送驱动指令、接收下行消息。
						文本驱动指令（WebSocket）		建立长连接通道后，可以通过 WebSocket 长连接发送文本驱动数智人。
						流式文本驱动指令（WebSocket）		建立长连接通道后，可以通过 websocket 长连接发送流式文本驱动数智人。
						音频驱动指令（WebSocket）		建立长连接通道后，可以通过 websocket 长连接发送音频驱动数智人。
						心跳指令（WebSocket）		在超过10分钟后如果云端未收到任何驱动指令会自动断开连接并释放并发。创建长通道后，通过发送心跳指令，可对会话进行续期。发送间隔大于30s，小于10分钟
		直接驱动(HTTPS)			文本驱动指令（HTTP 短连接）	POST /v2/ivh/interactdriver/interactdriverservice/command	HTTP方式发送文本驱动指令说明：不用建立长连接通道，常用于试用、一句话驱动等场景。
其他接口	实时更新数智人画面参数					POST /v2/ivh/sessionmanager/sessionmanagerservice/updatesessionconfig	用于实时更新视频流画面中的人物大小、位置、背景图。此接口不再建议使用，后续不再继续迭代新特性。
其他接口		获取进入 TRTC 房间秘钥					POST /v2/ivh/sessionmanager/sessionmanagerservice/gettrtcsign	当创建直播会话时选择了 trtc 协议，除数字人之外的其他用户若需加入房间使用此接口获取该用户的入房秘钥。

云渲染会话交互服务 API 概述

本页目录：

调用前须知

接口调用环境

接口调用方式

交互数智人 API 概览

接口接入流程

接入指引

接入流程