1.2 快速开始

本章提供一个最小可用示例，帮助你在 5 分钟内跑通数字人渲染。

前置条件

在开始之前，确保你已具备：

创建驱动应用，设置虚拟人角色、音色、表演风格，获取App ID、App Secret

请登录魔珐星云，在应用中心创建驱动应用，选择角色、音色、表演风格。
复制获取App ID和App Secret

第一步：引入 SDK

在页面中通过 <script> 标签引入 SDK 文件，SDK 会自动将 XmovAvatar 暴露到 window 全局对象上。

<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar@latest.js"></script>

引入后即可通过 window.XmovAvatar 使用。

第二步：准备容器

<div id="avatar-container" style="width: 360px; height: 640px;"></div>

注意：容器必须有明确的宽高，SDK 会在容器内创建 Canvas 元素进行渲染。

第三步：初始化与启动

// 1. 创建实例
const avatar = new XmovAvatar({
  containerId: '#avatar-container',  // 容器 CSS 选择器
  appId: 'your-app-id',              // 应用 ID
  appSecret: 'your-app-secret',      // 应用密钥
  gatewayServer: 'https://nebula-agent.xingyun3d.com/user/v1/ttsa/session', // 网关地址（固定值）

  // 错误回调（必须）
  onMessage(error) {
    console.error('SDK 错误:', error.code, error.message);
  },

  // 状态变化回调（推荐定义）
  onStatusChange(status) {
    console.log('状态变更:', status);
  },
});

// 2. 初始化（加载资源、建立连接，完成后自动启动渲染）
await avatar.init({
  onDownloadProgress(progress) {
    console.log('加载进度: ', `${progress}%`);
  },
});

第四步：发送语音

// 让数字人说话（SSML 格式）
avatar.speak('<speak>你好，我是你的数字人助手！</speak>');

第五步：清理资源

// 页面卸载时销毁实例
window.addEventListener('beforeunload', () => {
  avatar.destroy('page_unload');
});

完整示例

注意：请将示例中的 your-app-id 和 your-app-secret 替换为你自己的 App ID 和 App Secret，否则数字人无法正常加载。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>数字人快速开始</title>
  <style>
    #avatar-container {
      width: 360px;
      height: 640px;
      margin: 20px auto;
      border: 1px solid #eee;
    }
  </style>
</head>
<body>
  <div id="avatar-container"></div>

  <!-- 引入 SDK -->
  <script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar@latest.js"></script>

  <script>
    const avatar = new XmovAvatar({
      containerId: '#avatar-container',
      appId: 'your-app-id',
      appSecret: 'your-app-secret',
      gatewayServer: 'https://nebula-agent.xingyun3d.com/user/v1/ttsa/session',
      onMessage(error) {
        console.error('SDK 错误:', error.code, error.message);
      },
      onStatusChange(status) {
        console.log('状态变更:', status);
      },
    });

    avatar.init({
      onDownloadProgress(progress) {
        console.log('加载进度:', `${progress}%`);
      },
    }).then(() => {
      // 示例：3 秒后让数字人说话
      setTimeout(() => {
        avatar.speak('<speak>你好，这里是魔珐星云！</speak>');
      }, 3000);
    }).catch((err) => {
      console.error('初始化失败:', err);
    });

    window.addEventListener('beforeunload', () => {
      avatar.destroy('page_unload');
    });
  </script>
</body>
</html>

运行效果

成功初始化后，你将看到：

容器中出现数字人画面
调用 speak() 后数字人开始说话，口型和表情与语音同步