> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/get-started.md).

# 开始使用 Convai Embody

创建一个新的 React 应用，使用 Convai Embody 将 Convai 角色渲染为 3D 形象，并通过 Convai 聊天小组件在同一个连接上与其交谈。

构建一个页面，将 Convai 角色显示为 3D 身体，并让你能够与它交谈。可将此页面用作第一个项目：从空文件夹开始，最终实现一个能用语音回答你并同步口型的角色。聊天小组件是整个设置的一部分，而不是额外功能，因为无法交谈的身体只是一张图片。

### 前提条件

* Node.js 18 或更高版本，以及一个包管理器。
* 一个 Convai 帐户、从 <code class="expression">space.vars.dashboard\_url</code>获取的 API 密钥，以及一个角色 ID。
* 角色的头像必须已发布 Web 身体，或有适用于该角色的默认身体。两者都没有的角色无法渲染。请参阅 [故障排除](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md#troubleshooting).

### 创建应用

使用 Vite 创建 React 应用，并安装 Convai Embody、聊天小组件及其依赖项。 `@convai/web-sdk` 负责连接， `three` 和 `@react-three/fiber` 负责绘制身体，而 `@convai/web-widget` 则是聊天面板。

{% tabs %}
{% tab title="npm" %}

```bash
npm create vite@latest my-character -- --template react
cd my-character
npm install @convai/embody @convai/web-widget @convai/web-sdk three @react-three/fiber
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm create vite my-character --template react
cd my-character
pnpm add @convai/embody @convai/web-widget @convai/web-sdk three @react-three/fiber
```

{% endtab %}
{% endtabs %}

### 添加凭据

将 API 密钥和角色 ID 放入项目根目录下的 `.env` 文件中。Vite 会将以 `VITE_` 开头的变量公开给页面。

{% code title=".env" %}

```bash
VITE_CONVAI_API_KEY=YOUR_API_KEY
VITE_CONVAI_CHARACTER_ID=YOUR_CHARACTER_ID
```

{% endcode %}

{% hint style="danger" %}
API 密钥是工作区级别的凭据。任何打开包含该密钥的页面的人都能读取它。对于这样的本地项目，使用 API 密钥是合适的。对于公开页面，请在服务器上创建一个短时有效的身份验证令牌，并传入 `token` 而不是 `apiKey`。请参阅 [身份验证令牌](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/auth-tokens.md).
{% endhint %}

### 渲染角色和聊天小组件

将生成的 `src/App.jsx` 替换为下面的组件。 `ConvaiCharacter` 自带画布、摄像机、灯光和轨道控制器，会解析角色的身体、建立连接并驱动面部动作。 `onReady` 会在角色身体加载完毕且连接建立后，将角色交给你。小组件使用同一个连接，因此聊天和口型同步共用一个会话。

{% code title="src/App.jsx" %}

```jsx
import { useState } from 'react'
import ConvaiCharacter from '@convai/embody/react'
import { ConvaiWidget } from '@convai/web-widget/react'

export default function App() {
  const [client, setClient] = useState(null)

  return (
    <>
      <ConvaiCharacter
        apiKey={import.meta.env.VITE_CONVAI_API_KEY}
        characterId={import.meta.env.VITE_CONVAI_CHARACTER_ID}
        onReady={(character) => setClient(character.client)}
      />
      {client && <ConvaiWidget convaiClient={client} />}
    </>
  )
}
```

{% endcode %}

如果角色启用了长期记忆，连接还需要一个最终用户 ID，以便角色区分不同用户。请传入使用你应用的用户的稳定 ID： `session={{ endUserId: user.id }}`。如果没有此 ID，连接会失败，并显示 "Missing end\_user\_id"。

请勿使用 Web SDK 的 `useConvaiClient`来创建小组件的客户端。这个钩子会构造另一个 `ConvaiClient`，从而建立第二个连接：小组件会与一个会话通信，而角色的口型同步却对应另一个会话，因此角色会保持沉默。

移除生成的样式，让角色铺满窗口。将 `src/index.css` 替换为：

{% code title="src/index.css" %}

```css
html, body, #root { margin: 0; height: 100%; }
```

{% endcode %}

### 运行应用

```bash
npm run dev
```

打开输出的网址。首次访问时，主体内容会先下载，这需要几秒钟。随后角色会出现在页面中央、与视线齐平的位置，并播放待机动画；拖动可环绕角色转动视角，滚动可拉近距离，角色的眼睛会跟随镜头。聊天启动器位于右下角。

### 与角色交谈

点击启动器。小组件会以语音模式打开，并显示角色的名字和肖像。若要改为输入文字，请点击 **退出语音模式**，在 **对话** 框中输入消息，然后按 Enter。首次使用语音模式时，系统会请求麦克风访问权限。

{% hint style="success" %}
回复会显示在小组件中，角色会将其朗读出来，并随语音同步做出口型。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/18f69839ea3fe0b72ec1f088f4f63b6f58448938" %}
[将 3D 角色添加到 React 应用](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md)
{% endcontent-ref %}

{% content-ref url="/pages/afcae56dd5bee11232aa7e5af42d7608c0a2f044" %}
[React API 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/react-api-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/get-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
