别再卷大模型了，给你的 AI 产品一张脸

这两年所有人都在卷模型。参数、上下文长度、Agent 规划能力，发布会一个接一个。但你有没有发现一件有点尴尬的事：再聪明的 AI，用户面对的还是一个冷冰冰的聊天框。想让它开口说话、有表情、带动作，传统做法得组个团队，懂实时渲染的、搞音视频同步的、做 TTS 和动作驱动的，三个月起步。

上周我试了魔珐星云的具身驱动 SDK，搭一个开源的 Claude Code skill，5 分钟在网页里跑出一个能开口、有口型有表情的 3D 数字人。这篇记一下流程，以及我踩了一下午的坑。

邀请码：XDUAEIXZ8E，注册后免费获得1000积分，也就是2000分钟的免费调用额度，基本demo直接调通！
邀请码：XDUAEIXZ8E，注册后免费获得1000积分，也就是2000分钟的免费调用额度，基本demo直接调通！
邀请码：XDUAEIXZ8E，注册后免费获得1000积分，也就是2000分钟的免费调用额度，基本demo直接调通！

视频demo

一、为什么要给 AI 加个"身体"

先把话说在前头：数字人不是万金油。写代码、做数据分析、跑自动化流程，加个数字人形象纯属多余。但有一类场景我觉得真的需要，比如客服、教育陪练、虚拟陪伴、新闻播报、展会导览。这些场景里用户在意的不是模型能不能拿 SOTA，而是对着屏幕说话时有没有"温度"。一个会点头、会挑眉、口型对得上的形象，跟纯文本框比，留存和时长数据差得挺明显。

自己做的门槛在哪？

• 实时渲染这块，WebGL 加骨骼动画加表情融合（blendshape），光让它在浏览器里跑起来就得调半天。
• TTS 出来的 PCM 音频流得跟口型帧对齐，差个 200ms 用户立刻出戏。
• 光张嘴不行，还得有 idle 动作、说话时的手势、情绪切换。

魔珐星云做的事情很直接：把这一整套封成一个前端 SDK。引一个 JS 文件，new 一个对象，调一句 speak()，其他不用管。

二、三步跑起来

官方给了邀请码，我直接放在第一步。

第一步，打开官网 https://xingyun3d.com 注册账号，邀请码

XDUAEIXZ8E

第二步，进控制台创建一个"驱动应用"，挑角色形象、音色、表演风格。创建完会拿到一对凭据，App ID 和 App Secret（有些地方叫 AppKey）。复制存好，初始化要用。

第三步，把开源 skill 拉下来：

git clone https://github.com/windofbarcelona/mofaxingyun-avatar

这是个 Claude Code skill，把官方的 xmovAvatar SDK 封装成一个零构建的单文件 HTML。让 Claude Code 跑一下这个 skill，它会在工作目录生成一个 xingyun-avatar.html。配置弹层、加载进度、输入框、字幕、重连、音频补丁都写好了，不用自己搭。

进目录起本地服务：

python3 -m http.server 8080
# 浏览器打开 http://localhost:8080/xingyun-avatar.html

首次打开页面会让你填 App ID 和 App Secret，存在 localStorage 里。等进度条到 100%，状态灯变绿，输入框敲一句"你好，我是数字人助手"按回车。数字人张嘴念这句话的时候，口型、表情、手势都是对上的。第一次看到还是有点意思的。

三、SDK 本身怎么接

不想用 skill 也行，核心代码没几行。先引 SDK：

<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar@latest.js"></script>
<div id="avatar-container" style="width:100%;height:600px;"></div>

初始化：

const avatar = new XmovAvatar({
  containerId: '#avatar-container',
  appId: '你的 AppID',
  appSecret: '你的 AppSecret',
  gatewayServer: 'https://nebula-agent.xingyun3d.com/user/v1/ttsa/session',
  onMessage(err) {
    console.error('[avatar]', err);
  },
  onStatusChange(status) {
    // status 是数字枚举：0=online, 1=offline, 4=close
    if (status === 0) console.log('数字人上线');
  },
});

await avatar.init({
  onDownloadProgress(p) {
    console.log('资源加载中', (p * 100).toFixed(1) + '%');
  },
});

avatar.speak('<speak>你好，我是数字人助手</speak>');

window.addEventListener('beforeunload', () => {
  avatar.destroy('page_unload');
});

鉴权 SDK 内部自己搞定。请求头会带 X-APP-ID、X-TIMESTAMP、X-TOKEN，签名算法是 X-TOKEN = md5(小写路径 + 小写method + 排序去空格JSON + appSecret + 时间戳)。想搞懂原理查官方文档 52-192，接的时候不用碰。

几个常用 API：

API	作用
new XmovAvatar(config)	创建实例，传容器、凭据、网关、回调
avatar.init({onDownloadProgress})	加载资源、建立 TTSA 会话
avatar.speak('<speak>文本</speak>')	驱动数字人朗读，支持 SSML
avatar.destroy(reason)	销毁实例，页面卸载必调
onStatusChange(status)	监听连接状态，注意是数字枚举

浏览器要 Chrome 94+、Edge 94+ 或 Safari 15+，得支持 WebGL 2.0。我自己在 Chrome 上跑最稳。

四、四个坑，我替你们踩过了

官方文档能让 demo 跑起来，但离能用还差一截。这几个坑要是没人告诉你，每个都够你查一晚上。

第一个坑，onStatusChange 回来的状态是数字，不是字符串。SDK 源码里 AvatarStatus 是 online=0, offline=1, close=4。我想当然写了句 if (status === 'online') 来启用输入框，结果输入框灰了一晚上死活点不动。改成 status === 0 就好了，保险起见在 init().then() 里再兜底启用一次 UI。

第二个坑，千万别图省事双击 HTML 文件用 file:// 打开。这是我浪费时间最多的一个。数字人能加载、能动，就是不出声，控制台报 [PCMAudioPlayer] 请先调用init()初始化播放器。SDK 的 PCM 音频引擎用了 AudioWorklet，浏览器在 file:// 下出于安全限制不让加载，而且是静默失败，不会给你明确报错。必须起 HTTP 服务，从 http://localhost:PORT/xxx.html 进。看一眼地址栏，是 file 开头就赶紧关了。

第三个坑有点离谱，是 SDK 自己的 bug。PCMAudioPlayer.init() 异步加载 AudioWorklet，但 SDK 构造时没 await。如果你第一帧 TTS 音频在 Worklet 准备好之前到了，渲染循环调 start() 直接抛错，然后整个会话都没声音。HTTP 也救不了你。我在 skill 模板里写了个轮询补丁，等播放器真正 ready 再放行 start()，加了一堆诊断日志。自己接的话这段别省。

第四个，SDK 注入的 canvas 等元素 z-index 有 1000。我给设置弹层写了 z-index: 50，按钮怎么点都没反应，后来发现是被数字人 canvas 压在下面。模态层直接 z-index: 99999。

还有两个零碎的。重连之前先 document.getElementById('avatar-container').innerHTML = '' 把旧 canvas 清掉，保存的 initPromise 也要置空，否则重连时会复用旧 promise，看起来点了没反应。另外 speak() 的文本要包 <speak> 标签，< > & ' " 这些字符得做 XML 转义，用户输入个特殊字符 SSML 就炸了。

五、值不值得用

说实话体验比我预期好。5 分钟跑通不是夸张，不构建、不 npm、不挑框架，一个 HTML 文件扔服务器就能用。鉴权、资源加载、TTS、口型同步、动作融合 SDK 都包了，开发者实际要碰的就是 init/speak/destroy。开源 skill 模板把上面那些坑全补丁了，配置持久化、快捷短语、字幕、重连都有，拿去当产品原型演示没问题。

但也别指望它开箱即用解决所有事。这个 demo 没有大模型大脑，speak() 只是把你给它的文本念出来，不接收用户消息、不调 LLM。要做能对话的产品，外面得自己套一层：把用户输入发给 LLM，拿到回复再喂给 speak()。AppSecret 直接放前端跟官方"快速开始"示例一致，做 demo 没事，真上生产必须加服务端签名代理，不然密钥等于裸奔。WebGL 2.0 这个门槛也卡死了一部分老设备和手机浏览器。那个竞态 bug 虽然能绕，但总归是个隐患，等官方修吧。

我的看法是这样：如果你在做客服、陪练、播报、导览这类产品，想快速验证"加个数字人形象到底能不能提升数据"，魔珐星云是我目前试过上手成本最低的一条路。模型那一层该怎么接还怎么接，它只管"脸和嘴"，而且管得还行。

上生产就记住两件事：AppSecret 挪到后端代理，对话逻辑接个 LLM。其他的 SDK 基本能兜住。