1.2 快速开始

本节提供一个最小完整示例，帮助你在数分钟内跑通「创建实例 → 初始化 → 文本对话 → 语音识别 → 打断 → 销毁」的完整链路。

前置条件

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

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

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

此外，页面需运行在 HTTPS 或 localhost，并准备一个有明确宽高的容器（见下方示例）。

完整示例

下面是一个可复制即用的最小HTML页面，通过 <script> 标签加载 CDN 版本，直接使用全局构造器 XingyunAvatarAgent：

注意：请将示例中的 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>
    #agent-avatar {
      width: min(100%, 405px);
      aspect-ratio: 9 / 16;
      margin: 0 auto;
      overflow: hidden;
      background: #000;
    }
    .toolbar {
      display: flex;
      gap: 8px;
      margin: 12px auto;
      width: min(100%, 405px);
    }
  </style>
</head>
<body>
  <div id="agent-avatar"></div>
  <div class="toolbar">
    <button id="ask-btn">发文本</button>
    <button id="start-asr-btn">开始识别</button>
    <button id="stop-asr-btn">停止识别</button>
    <button id="interrupt-btn">打断</button>
    <button id="destroy-btn">销毁</button>
  </div>

  <!-- 通过 CDN 加载 SDK，SDK 会自动将 XingyunAvatarAgent 暴露到 window 全局对象 -->
  <script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar_e2e@latest.js"></script>

  <script>
    // ⚠️ 请将下面两项替换为你自己的 App ID 与 App Secret
    const appId = "your-app-id";
    const appSecret = "your-app-secret";

    // 1. 创建实例
    const agent = new window.XingyunAvatarAgent({
      container: document.getElementById("agent-avatar"),
      appId,
      appSecret,
      gatewayServer: "https://nebula-agent.xingyun3d.com/user/v1/ttsa_v2/session",
      onMessage(error) {
        console.error("渲染错误", error.code, error.message);
      },
      agentCallbacks: {
        onAgentStateChange(state) {
          console.log("Agent 状态", state);
        },
        onASRResult(result) {
          console.log("识别结果", result.text, result.isFinal ? "（最终）" : "");
        },
        onConversationChange(event) {
          console.log("对话状态", event.state);
        },
        onError(error) {
          console.error("Agent 错误", error.code, error.message);
        },
      },
    });

    // 2. 初始化（建立三条连接，返回后即进入 running，可直接对话/识别）
    agent
      .init({
        onDownloadProgress(progress) {
          console.log("资源下载进度", progress.toFixed(0) + "%");
        },
      })
      .catch((error) => {
        console.error("初始化失败", error);
      });

    // 3. 文本对话（ASR → Brain → 具身智能体播报）
    document.getElementById("ask-btn").addEventListener("click", async () => {
      await agent.ask("你好，介绍一下这个产品");
    });

    // 4. 语音识别（应由用户手势触发）
    document.getElementById("start-asr-btn").addEventListener("click", async () => {
      try {
        await agent.startASR();
      } catch (error) {
        console.error("识别启动失败", error);
      }
    });
    document.getElementById("stop-asr-btn").addEventListener("click", async () => {
      await agent.stopASR();
    });

    // 5. 客户端打断当前播报
    document.getElementById("interrupt-btn").addEventListener("click", () => {
      agent.interrupt("speak");
    });

    // 6. 销毁（页面退出或组件卸载时调用）
    document.getElementById("destroy-btn").addEventListener("click", async () => {
      await agent.destroy("user");
    });
    window.addEventListener("beforeunload", () => {
      void agent.destroy("page_unload");
    });
  </script>
</body>
</html>

先点「发文本」验证文本对话，再点「开始识别」验证麦克风链路，最后点「打断」与「销毁」。