Skip to Content
JavaScript SdkQuick start

Quick start

在网页里放一个实时对话的数字人。SDK 加入你的服务器创建的会话，在 <video> 元素里显示数字人，播放它的声音， 把用户的麦克风声音发过去，并实时给你字幕和角色的客户端工具调用。

开始之前

你需要从 AvatarGo 控制台 拿到两样东西：

  • 一个 API key。 在控制台打开 API Keys，按 Create key。key 只显示这一次：当场复制， 保存在你的服务器上，比如放进环境变量 AVATARGO_API_KEY。它永远不进网页。见 Authentication。
  • 一个已发布的角色。 在 Build 里搭建：一张脸、一个声音，以及它该说什么。按 Publish——用你的 API key 创建的会话只用已发布的版本——然后按页面顶部的 Copy character ID。角色 ID 以 ch_ 开头。

安装

npm install @avatargo/sdk

它是一个 ES 模块，基于 livekit-client，这也是它唯一的依赖。

不用打包工具

普通 HTML 页面可以用 import map 从 CDN 加载这两个包，然后像下面你的页面一样 import。 两个版本都要固定：livekit-client 用这一版 SDK 构建时所用的版本。

<script type="importmap">
{ "imports": {
  "@avatargo/sdk": "https://cdn.jsdelivr.net/npm/@avatargo/sdk@0.1.0/dist/index.js",
  "livekit-client": "https://cdn.jsdelivr.net/npm/livekit-client@2.22.3/dist/livekit-client.esm.mjs"
} }
</script>
<script type="module">
  import { createClient } from "@avatargo/sdk";
  // … Quick start 里页面的代码
</script>

会话怎么建立

你的 API key 永远不进浏览器。 分两步，在两个地方：

  1. 你的服务器用 API key 向 AvatarGo 要一个会话：POST /v1/auth/session-token。拿回一个 sessionToken，有效期一小时。
  2. 浏览器从你的服务器拿到这个 token，交给 SDK。SDK 用它换取会话房间里的位置，然后加入。
browser ──(1) "start a call"──▶ your server ──POST /v1/auth/session-token (API key)──▶ AvatarGo
browser ◀──── sessionToken ──── your server ◀──────────── { sessionToken, sessionId } ─┘
browser ──(2) createClient(sessionToken).streamToVideoElement(…) ──▶ AvatarGo + the avatar

会话有两种，由你的服务器在创建时决定：

  • 角色（characterId，或在请求里直接写出的 characterConfig）：角色听用户说话并回答。SDK 发送麦克风声音、 显示字幕。这是最常见的用法，也是本页讲的。
  • Avatar only：你的服务器自己发送语音音频，数字人跟着对口型。页面只显示数字人——加入时用 { microphone: false }。没有字幕，也没有客户端工具。见 Avatar only (your own audio)。

你的服务器

你自己的接口，用 Node 或 Python：

任何框架都行——这里用最简单的 fetch。

// POST /api/avatar-session —— 你自己的接口，由你的页面调用。
const res = await fetch("https://api.avatargo.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.AVATARGO_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ characterId: "ch_…" }),   // 你在控制台搭建并发布的角色
});
const body = await res.json();
// 拒绝在这里返回，还没到页面——比如套餐的同时通话数已用满时返回 concurrency_limit。
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { sessionToken } = body;
// 把 { sessionToken } 发给页面

你的页面

<video id="avatar" autoplay playsinline></video>
<button id="start">Talk</button>
<button id="stop">End</button>
import { createClient } from "@avatargo/sdk";
 
let client;
document.getElementById("start").onclick = async () => {
  const { sessionToken } = await (await fetch("/api/avatar-session", { method: "POST" })).json();
  client = createClient(sessionToken);
  client.on("message", (m) => console.log(m.role, m.content, m.final)); // 实时字幕
  client.on("session_ended", () => console.log("ended"));
  await client.streamToVideoElement("avatar"); // 请求麦克风、加入会话、显示数字人
};
document.getElementById("stop").onclick = () => client?.stopStreaming();

像这里一样，从一次点击开始：浏览器只有在用户和页面交互之后，才会播放声音、请求麦克风。

Pre-renderReference