> 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/convai-pixel-streaming-embed/api-reference.md).

# Pixel Streaming Embed API 参考

React 组件、无框架客户端、它们的选项和方法、它们报告的事件以及它们显示的错误的参考文档。

`@convai/experience-embed` 导出一个 React 组件， `PixelStreamComponent`以及一个不依赖框架的类， `PixelStreamClient`。两者都会在 iframe 中渲染 Convai Pixel Streaming 体验，并使用相同的选项，除了本页中注明的差异。

### 入口点

| 导入                                                | 格式               | 导出                                                                                                                                   |
| ------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@convai/experience-embed`                        | ES 模块            | `PixelStreamComponent`, `getPixelStream`，以及类型 `PixelStreamComponentProps`, `PixelStreamComponentHandles`, `EndUserId`，以及 `ChatStyle` |
| `@convai/experience-embed/core`                   | UMD， `require` 仅 | `PixelStreamClient`，以及类型 `PixelStreamOptions`, `EndUserId`，以及 `ChatStyle`                                                            |
| `dist/core/convai-embed.umd.js` 由一个 `<script>` 标签 | UMD              | 全局 `PixelStreamCore`，其 `PixelStreamClient` 属性是该类                                                                                     |

UMD 文件是自包含的。ES 模块会导入 `react` 来自你的应用。该包声明 `react` 和 `react-dom` `^18.3.1` 作为依赖项。

### PixelStreamComponent 属性

| 属性                       | 类型                                                    | 默认值                | 描述                                                                                                              |
| ------------------------ | ----------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `expId`                  | `字符串`                                                 | 必填                 | 已发布体验的体验 ID。                                                                                                    |
| `authToken`              | `字符串`                                                 | 无                  | 由你的服务器签发的 Convai auth token。设置后，它会授权该会话，而不是使用页面的域名。更改它会启动一个新会话。                                                 |
| `endUserId`              | `字符串`                                                 | 无                  | 你为使用该体验的人设置的标识符。在会话创建时发送，并绑定到该会话。更改它会启动一个新会话。空值或仅包含空白字符的值会从会话请求中省略。                                             |
| `endUserMetadata`        | `Record<string, any>`                                 | 无                  | 关于终端用户的额外详情，与 `endUserId`。仅当 `endUserId` 已设置时。                                                                  |
| `InitialScreen`          | `React.ReactNode`                                     | 一个 **点击开始你的体验** 屏幕 | 在体验开始前显示。自定义屏幕不会在点击时启动体验；请调用 `initializeExperience()`.                                                          |
| `LoadingScreenComponent` | `React.ReactNode`                                     | 无                  | 在 iframe 上方显示，直到流页面报告它已完成加载。                                                                                    |
| `chatStyle`              | `ChatStyle`                                           | 无                  | 内置聊天窗口的外观。在体验运行期间应用更改。                                                                                          |
| `serviceUrls`            | `{ sessionFetch?: string; pixelStreamBase?: string }` | Convai 的服务         | 自托管服务 URL。参见 [配置本地部署](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/on-premise-deployment.md). |
| `avatarStudio`           | `布尔值`                                                 | 无                  | 当 `true`时，请求 `vhh_character_creator` 会话模式。                                                                      |
| `ref`                    | `React.Ref<PixelStreamComponentHandles>`              | 无                  | 接收下一节列出的这些方法。                                                                                                   |

该组件还会将 [回调](#callbacks) 中的每个回调作为属性。它会填充其父元素，因此请为父元素设置宽度和高度。

### PixelStreamComponentHandles

组件的 `ref`上可用的方法。一个在流页面加载前调用的方法不会发送任何内容：

| 方式                                        | 返回                 | 描述                                                        |
| ----------------------------------------- | ------------------ | --------------------------------------------------------- |
| `initializeExperience()`                  | `void`             | 用体验替换初始屏幕。                                                |
| `sendMessageToCharacter(message: string)` | `void`             | 向角色发送一条文本消息。                                              |
| `beginVoiceInteraction()`                 | `void`             | 向体验发送开始语音输入的信号。                                           |
| `endVoiceInteraction()`                   | `void`             | 向体验发送停止语音输入的信号。在免提体验中，角色仍会继续听到用户；请改用 `muteMicrophone()` 。 |
| `muteMicrophone()`                        | `void`             | 在对话继续进行时将用户的麦克风静音。流重新连接时，静音状态会保留。 `onMicStatus` 报告何时已应用。  |
| `unmuteMicrophone()`                      | `void`             | 取消用户麦克风静音。                                                |
| `enableCamera()`                          | `Promise<boolean>` | 打开用户的摄像头。流页面报告摄像头状态时解析： `true` 如果摄像头已开启。                  |
| `disableCamera()`                         | `Promise<boolean>` | 关闭用户的摄像头。解析 `true` 当流页面报告摄像头已关闭时。                         |
| `enableCharacterAudio()`                  | `void`             | 取消角色音频静音。                                                 |
| `disableCharacterAudio()`                 | `void`             | 将角色音频静音。                                                  |
| `setChatStyle(style: ChatStyle)`          | `void`             | 更改聊天外观。优先使用 `chatStyle` 属性。                               |

当体验显示其内置聊天且你尚未调用 `muteMicrophone()` 或 `unmuteMicrophone()`，麦克风会以静音状态开始。

### PixelStreamClient 选项

```ts
new PixelStreamClient(options: PixelStreamOptions)
```

构造函数会请求一个会话并渲染到 `容器` 中，无需进一步调用。

| 选项                       | 类型                                                    | 默认值                | 描述                                                                                                              |
| ------------------------ | ----------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `容器`                     | `HTMLElement`                                         | 必填                 | 体验渲染到其中的元素。其内容会被替换。                                                                                             |
| `expId`                  | `字符串`                                                 | 必填                 | 已发布体验的体验 ID。                                                                                                    |
| `authToken`              | `字符串`                                                 | 无                  | 由你的服务器签发的 Convai auth token。设置后，它会授权该会话，而不是使用页面的域名。                                                             |
| `endUserId`              | `字符串`                                                 | 无                  | 你为使用该体验的人设置的标识符，在会话创建时与会话绑定。                                                                                    |
| `endUserMetadata`        | `Record<string, any>`                                 | 无                  | 关于终端用户的额外详情。仅当 `endUserId` 已设置时。                                                                                |
| `InitialScreen`          | `HTMLElement`                                         | 一个 **点击开始你的体验** 屏幕 | 在体验开始前显示。自定义屏幕不会在点击时启动体验；请调用 `initializeExperience()`.                                                          |
| `LoadingScreenComponent` | `HTMLElement`                                         | 无                  | 在 iframe 上方显示，直到流页面报告它已完成加载。                                                                                    |
| `chatStyle`              | `ChatStyle`                                           | 无                  | 内置聊天窗口的初始外观。                                                                                                    |
| `serviceUrls`            | `{ sessionFetch?: string; pixelStreamBase?: string }` | Convai 的服务         | 自托管服务 URL。参见 [配置本地部署](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/on-premise-deployment.md). |
| `avatarStudio`           | `布尔值`                                                 | 无                  | 当 `true`时，请求 `vhh_character_creator` 会话模式。                                                                      |

`PixelStreamClient` 也会将 [回调](#callbacks) 中的每个回调作为

### PixelStreamClient 方法

`PixelStreamClient` 拥有 `PixelStreamComponentHandles`的方法，但有以下差异：

| 方式                                                  | 差异                                                            |
| --------------------------------------------------- | ------------------------------------------------------------- |
| `enableCharacterAudio()`, `disableCharacterAudio()` | 返回值 `Promise<boolean>`，它会在 `true` 消息发送后解析。                    |
| `setChatStyle(style: ChatStyle)`                    | 将 `样式` 合并到当前样式中，因此你省略的字段会保留其值。可以在体验加载前调用。                     |
| `destroy()`                                         | 仅在 `PixelStreamClient`。停止监听来自流页面的消息。它不会移除 iframe；请自行清除 `容器` 。 |

### 回调

每个回调都会在流页面发布匹配消息时触发。回调内部抛出的错误会记录到控制台，并且不会停止嵌入：

| 回调                   | 触发时                                                                   | 载荷                                                                                                         |
| -------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `onIframeLoaded`     | 流页面已加载。每个会话一次。                                                        | `null`                                                                                                     |
| `onCharacterMessage` | 用户或角色会说些什么。角色的回复会分段到达。                                                | 来自体验的消息对象，包括 `message`，文本； `player`, `true` 用于用户自己的台词； `endofmessage`, `true` 在回复的最后一部分；以及 `sentenceready` |
| `onAfk`              | 流断开连接。                                                                | `'Disconnected'`                                                                                           |
| `onCameraStatus`     | 摄像头开启或关闭。                                                             | `布尔值`                                                                                                      |
| `onCameraStream`     | 体验开始或停止摄像头流。                                                          | `布尔值`                                                                                                      |
| `onUserUpdated`      | 体验更新用户详情。                                                             | `null`                                                                                                     |
| `onConfigChanged`    | 体验更改其配置。                                                              | `null`                                                                                                     |
| `onMicStatus`        | 流页面应用 `muteMicrophone()` 或 `unmuteMicrophone()`，用户选择内置聊天的麦克风按钮，或者流连接。 | `{ muted: boolean }`                                                                                       |

### ChatStyle

| 字段                  | 类型   | 默认值   | 描述                                                |
| ------------------- | ---- | ----- | ------------------------------------------------- |
| `backgroundOpacity` | `数字` | `0.7` | 聊天文本后方底板的不透明度，从 `0`，完全透明，到 `1`。输入字段和麦克风按钮按相同比例缩放。 |

超出 `0` 到 `1` 范围的值会被钳制，非数字值将被忽略。

### getPixelStream

```ts
getPixelStream(options: {
  exp_id: string
  exp_base?: string
  avatarStudio?: boolean
  end_user_id?: string
  auth_token?: string
}): Promise<{ loading: boolean; data: { session: { session_id: string } } | null; error: string | null }>
```

会话请求，该请求 `PixelStreamComponent` 在渲染 iframe 之前发起。它发送 `POST <exp_base>/xp/streams/viewPublishedExperience`，其中 `exp_base` 默认为 `https://api.convai.com`，并将 `auth_token` 放在 `API-AUTH-TOKEN` 请求头中。它不会抛出异常：失败会返回在 `error`.

### 错误

当会话请求失败时，嵌入会显示错误界面而不是体验：

| 条件                                           | 错误界面上的消息                        |
| -------------------------------------------- | ------------------------------- |
| 否 `authToken`，并且请求失败                         | `请联系 convai 以将 <origin> 加入白名单！` |
| `authToken` 已设置，并且 Convai 的错误提到了该 auth token | `此体验无法启动：Convai 认证令牌无效或已过期。`    |
| `authToken` 已设置，并且请求因其他原因失败                  | `此体验无法启动。请稍后重试。`                |

### 相关参考

{% content-ref url="/pages/160b67ed81203fc1670d38b8323bb9e39264f2cb" %}
[发布并授权体验](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/whitelisting-and-publishing-an-experience.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/convai-pixel-streaming-embed/api-reference.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.