腾讯云智能数智人全流程对接指南：从准备到落地（含代码示例）
腾讯云智能数智人全流程对接指南：从准备到落地（含代码示例）
随着人工智能技术的快速迭代，智能数智人已成为企业数字化转型的重要载体，广泛应用于客服咨询、直播带货、政务讲解、金融播报等场景。腾讯云智能数智人依托腾讯自研的AI能力与渲染技术，提供2D/3D写实、卡通等多风格形象，支持文本驱动、语音驱动、动作定制等核心能力，同时开放标准化的API与SDK，助力开发者快速将数智人集成至自有系统、APP、小程序或网页中。本文将从接入前准备、账号配置、接入模式选择、API/SDK集成、核心功能开发、安全认证到问题排查，全方位拆解腾讯云智能数智人的对接流程，结合多语言代码示例，帮助不同技术背景的开发者高效完成落地。
一、接入前核心准备：服务开通与账号体系搭建
在正式对接前，必须完成腾讯云账号注册、数智人服务开通、权限配置及密钥获取，这是后续所有对接操作的基础，任何环节缺失都会导致接口调用失败或权限异常。
1.1 账号注册与服务开通
首先需要拥有有效的腾讯云账号，若为企业用户，建议使用企业实名账号，避免个人账号权限限制影响后续服务购买与资源管理。
需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联
登录控制台后，进入「智能数智人」产品页面，根据业务需求选择服务版本：基础版适合小型企业或个人开发者，提供标准形象与基础交互能力，支持5路以内并发；高级版（iPaaS模式）面向中大型企业，支持租户隔离、自定义换肤、独立运营后台及高并发扩容，适合集成至自有SaaS系统或多终端统一管理场景。
服务开通分为两种方式：官网直接下单（基础版）、联系腾讯商务签署合约（高级版/定制化需求）。开通完成后，系统会生成唯一的租户标识（tenant_code）、客户标识（merchantID）及初始账号密码，用于后续登录态关联与接口认证。
1.2 密钥体系：永久AK/SK与临时AK/SK选择
腾讯云智能数智人接口调用采用「密钥签名认证」机制，核心凭证为SecretId（AK）与SecretKey（SK），支持永久密钥与临时密钥两种模式，安全等级与适用场景差异显著。
1.2.1 永久AK/SK（适合测试/内部系统）
永久密钥长期有效，无需频繁更新，获取路径简单，但泄露风险较高，仅建议用于内部管理系统、测试环境或低安全等级场景。
获取步骤：
- 登录腾讯云控制台，进入「访问管理」→「访问密钥」→「API密钥管理」；
- 点击「新建密钥」，系统生成SecretId与SecretKey，立即保存（SecretKey仅显示一次）；
- 企业用户建议创建子账号，为子账号分配「智能数智人相关权限」后生成子账号密钥，遵循最小权限原则，降低主账号泄露风险。
1.2.2 临时AK/SK（适合生产环境/高安全场景）
临时密钥通过腾讯云STS（安全令牌服务）生成，有效期可自定义（15分钟-24小时），过期自动失效，即使泄露也仅影响短期操作，是生产环境的首选方案。
临时密钥获取核心参数：
- policy：权限策略，仅授予数智人相关接口权限，示例如下：
{
"version": "2.0",
"statement": [
{
"effect": "allow",
"action": ["avatar:CreateSession", "avatar:SendDriverData"],
"resource": "*"
}
]
}
- durationSeconds：有效期，建议设为3600秒（1小时）；
- roleArn：角色ARN，需提前在访问管理创建「STS角色」并关联数智人权限。
1.3 数智人项目创建与核心参数获取
服务开通后，登录「腾讯云智能数智人交互平台」，创建专属数智人项目，每个项目对应独立的形象、并发配额与配置参数，核心参数如下，对接时必须准确填写：
- appkey：项目唯一标识，接口调用必传；
- accesstoken：项目访问令牌，与appkey配对使用；
- asset_virtualman_key：形象资产ID（优先使用），对应选定的数智人形象；
- virtualman_project_id：项目ID，asset_virtualman_key为空时使用；
- protocol：传输协议，支持rtmp（云渲染推流）、trtc（实时音视频）、webrtc（网页端实时通信）。
二、接入模式详解：基础版、高级版（iPaaS）与渲染模式选择
腾讯云智能数智人提供多种接入模式，核心分为「基础版接入」「高级版iPaaS接入」，同时按渲染位置分为「云渲染」与「端渲染」，不同模式适配不同业务场景，需根据并发量、终端类型、定制化需求选择。
2.1 基础版接入（适合小型项目/快速验证）
基础版接入流程简单，无需复杂的租户配置，核心是完成「Token校验回调接口」开发与登录态关联，适合单一场景、低并发（≤5路）需求，如企业官网客服、小程序咨询窗口。
2.1.1 核心对接流程
- 获取merchantID（客户标识），由腾讯数智人后台配置后提供；
- 生成AK/SK（永久/临时），关联腾讯云账号；
- 开发公网可访问的「Token校验回调接口」，用于数智人服务端校验客户端Token有效性；
- 将接口地址提交给腾讯商务或通过邮件同步给数智人团队；
- 客户端集成时，携带Token、merchantID等参数，完成登录态验证后加载数智人页面。
2.1.2 Token校验回调接口规范（POST）
请求参数（JSON）：
{
"token": "客户端生成的Token字符串",
"merchant_id": "客户标识",
"user_id": "终端用户ID"
}
返回参数（JSON，200成功）：
{
"code": 0,
"msg": "success",
"data": {
"valid": true,
"user_name": "用户名",
"expire_time": "过期时间戳"
}
}
2.2 高级版iPaaS接入（适合中大型企业/多终端集成）
高级版（iPaaS）是面向企业级集成的SaaS化方案，核心优势是「租户隔离、独立运营、自定义能力强」，支持集成商将数智人页面嵌入自有系统，打通用户登录态，自主管理换肤、货架、用户权益，适合SaaS平台、多品牌企业或高并发（≥10路）场景。
2.2.1 角色与权限体系
iPaaS模式包含三级角色，权限隔离清晰：
- 集成商（租户）：管理企业级配置、换肤、运营数据；
- 企业（B端客户）：集成商录入企业信息，管理企业成员权限；
- 终端用户（C/B端）：自主注册，集成商后台管理用户权益。
2.2.2 页面集成（iframe嵌入，网页端核心方案）
iPaaS模式下，网页端通过iframe嵌入数智人页面，引入官方JS SDK完成初始化，支持登录态透传、页面回调、自定义样式覆盖。
代码示例（HTML+JS）：
腾讯云数智人iPaaS集成
2.3 渲染模式：云渲染 vs 端渲染
渲染模式决定数智人画面的生成位置，直接影响终端性能、并发成本与画面质量，需根据终端设备性能、网络环境选择。
2.3.1 云渲染（推荐：低性能终端/高并发）
数智人形象在腾讯云服务器渲染，生成视频流（RTMP/TRTC）推送到客户端，客户端仅负责播放，无需消耗终端算力，适合手机小程序、低配APP、网页端，支持高并发，单路并发成本较低。
优势：终端性能要求低、适配广、并发扩容简单；劣势：依赖网络带宽，弱网下可能卡顿。
2.3.2 端渲染（适合：高性能终端/3D形象）
数智人渲染资源（模型、材质）下载到本地终端，由终端GPU实时渲染，画面质量高、延迟低，支持3D写实形象、复杂动作交互，适合高性能APP、智能硬件、大屏设备。
优势：本地渲染延迟低、画质高、支持复杂交互；劣势：终端需GPU支持、资源下载耗时、并发扩容成本高。
三、核心API对接：会话创建、驱动数据发送、流地址获取
无论基础版还是高级版，核心交互均通过「服务端API」完成，包括会话创建、驱动数据（文本/音频）发送、流地址获取、会话销毁等，接口采用RESTful规范，支持HTTP/HTTPS调用，返回JSON格式数据。
3.1 接口调用基础规范
3.1.1 公共参数（所有接口必传）
- appkey：项目appkey；
- timestamp：当前时间戳（秒）；
- nonce：随机字符串（防重放）；
- signature：签名（参数+SK加密生成，防篡改）。
3.1.2 签名生成算法（Python示例）
import hashlib
import time
import random
def generate_signature(secret_key, params):
sorted_params = sorted(params.items())
sign_str = "".join([f"{k}{v}" for k, v in sorted_params])
sign_str += secret_key
signature = hashlib.md5(sign_str.encode()).hexdigest()
return signature
params = {
"appkey": "your_appkey",
"timestamp": int(time.time()),
"nonce": str(random.randint(100000, 999999))
}
signature = generate_signature("your_secret_key", params)
3.2 核心API详解（含Python代码示例）
3.2.1 创建会话（CreateSession）
功能：初始化数智人会话，返回会话ID、流地址、连接参数，是所有交互的前提。
请求地址：https://gw-sg.tvs.qq.com/avatar/v4/CreateSession
请求方式：POST
请求参数（JSON）：
{
"appkey": "your_appkey",
"accesstoken": "your_accesstoken",
"asset_virtualman_key": "your_asset_key",
"protocol": "rtmp",
"user_id": "test_user_001"
}
Python调用示例：
import requests
import json
import time
import random
def generate_signature(secret_key, params):
sorted_params = sorted(params.items())
sign_str = "".join([f"{k}{v}" for k, v in sorted_params])
sign_str += secret_key
return hashlib.md5(sign_str.encode()).hexdigest()
CONFIG = {
"appkey": "your_appkey",
"accesstoken": "your_accesstoken",
"asset_virtualman_key": "your_asset_key",
"protocol": "rtmp",
"user_id": "test_user_001",
"api_url": "https://gw-sg.tvs.qq.com/avatar/v4/CreateSession"
}
params = {
"appkey": CONFIG["appkey"],
"timestamp": int(time.time()),
"nonce": str(random.randint(100000, 999999))
}
signature = generate_signature("your_secret_key", params)
request_data = {
**params,
"signature": signature,
"accesstoken": CONFIG["accesstoken"],
"asset_virtualman_key": CONFIG["asset_virtualman_key"],
"protocol": CONFIG["protocol"],
"user_id": CONFIG["user_id"]
}
response = requests.post(CONFIG["api_url"], json=request_data)
result = response.json()
if result["code"] == 0:
session_id = result["data"]["session_id"]
stream_url = result["data"]["stream_url"]
print(f"会话创建成功，会话ID：{session_id}，流地址：{stream_url}")
else:
print(f"会话创建失败：{result['msg']}")
返回参数（成功）：
{
"code": 0,
"msg": "success",
"data": {
"session_id": "xxxxxx",
"stream_url": "rtmp://xxx.xxx.xxx/live/xxxx",
"expire_time": 3600
}
}
3.2.2 发送驱动数据（SendDriverData）
功能：向数智人发送文本或音频数据，驱动数智人说话、做动作，支持实时流式传输。
请求地址：https://gw-sg.tvs.qq.com/avatar/v4/SendDriverData
请求方式：POST
请求参数（JSON）：
{
"appkey": "your_appkey",
"session_id": "会话ID",
"driver_type": "text",
"content": "你好，我是腾讯云智能数智人",
"is_end": true
}
关键说明：音频驱动时，音频格式必须为「PCM 16bit 16kHz 单声道」，数据需Base64编码后传输。
3.2.3 销毁会话（DestroySession）
功能：会话结束后调用，释放服务端资源，避免无效占用并发配额。
请求地址：https://gw-sg.tvs.qq.com/avatar/v4/DestroySession
请求参数：appkey、session_id、signature等公共参数。
四、端渲染SDK集成（Android/iOS/小程序）
端渲染模式需集成对应终端SDK，完成资源下载、本地渲染、音频驱动与动作控制，以下以Android SDK为例，核心讲解集成步骤与关键API调用。
4.1 Android SDK集成步骤
- 下载SDK包（.aar），放入项目libs目录；
- 配置build.gradle，添加依赖：
dependencies {
implementation files('libs/tencent-avatar-sdk.aar')
implementation 'com.squareup.okhttp3:okhttp:4.9.3'
}
- 添加权限（AndroidManifest.xml）：
4.2 核心API调用（Java代码示例）
4.2.1 初始化SDK与数智人控制器
import com.tencent.avatar.AvatarController;
import com.tencent.avatar.callback.InitCallback;
import android.util.Log;
AvatarController controller = new AvatarController(this);
controller.initHuman("your_appkey", "your_accesstoken", "your_asset_key", new InitCallback() {
@Override
public void onSuccess(String sessionId) {
Log.d("Avatar", "初始化成功，会话ID：" + sessionId);
}
@Override
public void onFailed(int code, String msg) {
Log.e("Avatar", "初始化失败：" + msg);
}
});
4.2.2 音频数据驱动（PCM流式推送）
byte[] audioData = loadPcmData(); controller.appendAudioData(audioData, true); controller.appendAudioData(chunk1, false, "metadata_1"); controller.appendAudioData(chunk2, false, "metadata_2"); controller.appendAudioData(chunk3, true, "metadata_final");
4.2.3 动作插入（精品模式支持）
controller.appendAction("wave_hand", System.currentTimeMillis());
五、长连接通信（WebSocket）：实时交互与状态同步
为实现低延迟实时交互（如实时语音对话、动作同步），数智人支持WebSocket长连接，用于驱动数据实时传输、状态回调、错误通知，连接地址：wss://gw-sg.tvs.qq.com。
5.1 连接建立（JavaScript示例）
const wsUrl = "wss://gw-sg.tvs.qq.com/avatar/v4/ws?appkey=your_appkey&session_id=your_session_id";
const socket = new WebSocket(wsUrl);
socket.onopen = function() {
console.log("WebSocket连接成功");
};
socket.onmessage = function(event) {
const msg = JSON.parse(event.data);
console.log("收到消息：", msg);
};
socket.onclose = function() {
console.log("WebSocket连接关闭");
};
function sendText(text) {
const data = {
driver_type: "text",
content: text,
is_end: true
};
socket.send(JSON.stringify(data));
}
六、安全认证与权限优化：避免泄露与非法调用
数智人对接涉及密钥、用户数据、会话信息等敏感数据，必须做好安全防护，核心措施如下：
- 密钥管理：生产环境强制使用临时AK/SK，密钥仅在服务端存储，禁止前端/客户端明文存储；
- Token校验：基础版必须实现Token回调校验，验证用户身份合法性；
- HTTPS加密：所有接口、WebSocket连接均使用HTTPS/WSS，防止数据劫持；
- 权限最小化：子账号仅分配数智人必要接口权限，禁止开放全量权限；
- 并发控制：根据业务规模申请合理并发配额，避免非法请求占用资源。
七、常见问题排查：快速解决对接异常
7.1 接口调用失败（签名错误）
排查点：参数排序是否正确、SK是否正确、时间戳是否过期（误差≤30秒）、nonce是否随机。
7.2 会话创建成功，但无画面
排查点：流地址是否正确、网络是否开放RTMP/TRTC端口、云渲染是否已启动、终端播放器是否支持对应协议。
7.3 音频驱动无反应
排查点：音频格式是否为PCM 16bit 16kHz单声道、数据是否Base64编码、driver_type是否设为audio、is_end是否正确。
7.4 端渲染资源下载失败
排查点：网络权限是否开启、存储空间是否充足、appkey/accesstoken是否正确、形象资产ID是否有效。
八、总结
腾讯云智能数智人对接是一套「从账号准备、模式选择、API/SDK集成到安全优化」的完整流程，核心在于根据业务场景选择合适的接入模式（基础版/高级版）与渲染模式（云渲染/端渲染），严格遵循接口规范与安全要求，结合代码示例快速完成开发。对于小型项目，基础版+云渲染可快速上线；对于中大型企业，高级版iPaaS+端渲染可满足高定制化、高性能需求。通过本文的全流程拆解与代码实践，开发者可快速突破对接难点，将智能数智人能力无缝集成至自有业务中，释放AI数字人的商业价值。
常见问答
Q1：腾讯云智能数智人基础版和高级版的核心区别是什么？
A1：基础版适合小型项目，流程简单、低并发（≤5路）、无租户隔离；高级版（iPaaS）面向企业级，支持租户隔离、自定义换肤、独立运营后台、高并发扩容，适合多终端集成与SaaS系统对接。
Q2：云渲染和端渲染如何选择？
A2：低配终端、网页、小程序以及高并发场景选择云渲染；高性能终端、3D形象、低延迟交互场景选择端渲染。
Q3：数智人音频驱动对音频格式有要求吗？
A3：有严格要求，音频必须为PCM编码、16bit位深度、16kHz采样率、单声道格式，传输过程中还需要做Base64编码处理。
Q4：生产环境推荐使用永久AK/SK还是临时AK/SK？
A4：生产环境优先使用STS生成的临时AK/SK，时效性强、泄露风险低；永久AK/SK仅用于测试环境和内部管理系统。
Q5：对接时出现签名错误，如何快速排查？
A5：依次检查参数是否按key升序排列、SecretKey是否填写正确、客户端与服务端时间戳误差是否在30秒内、随机字符串nonce是否正常生成。
Q6：会话创建成功但终端无画面，可能是什么原因？
A6：大概率是流地址错误、网络端口未放行、云渲染服务未正常启动，或是终端播放器不匹配当前传输协议。
