> 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/createcharacter-reference.md).

# createCharacter 参考

Convai Embody 中 createCharacter 函数的参考，包括每个选项、其默认值以及它返回的角色句柄。

`createCharacter` 从以下位置导出 `@convai/embody`。它会解析角色的身体、加载它、打开 Convai Web SDK 连接，并返回一个 `CharacterHandle`。React 组件接受相同的选项作为 props。

```typescript
函数 createCharacter(options: CreateCharacterOptions): Promise<CharacterHandle>
```

### 选项

`characterId` 并且需要一个凭证。其他所有选项都有可用的默认值。

#### 身份与连接

| 选项            | 类型                                                       | 默认值               | 说明                                                            |
| ------------- | -------------------------------------------------------- | ----------------- | ------------------------------------------------------------- |
| `characterId` | `string`                                                 | required          | 要渲染的角色。                                                       |
| `令牌`          | `string`                                                 | 无                 | Convai 身份验证令牌。在浏览器中使用的凭证。优先于 `apiKey`.                        |
| `authToken`   | `string`                                                 | 无                 | 与……相同 `令牌`，名称与 Convai Web SDK 使用的名称一致。                        |
| `apiKey`      | `string`                                                 | 无                 | Convai API 密钥。仅在受信任的上下文中使用。                                   |
| `baseUrl`     | `string`                                                 | 该版本的 Convai 主机    | 后端主机。仅在需要指向不同的 Convai 环境时更改。                                  |
| `会话`          | `SessionOptions` 不带 `characterId`, `apiKey`, `authToken` | 无                 | 额外的 Convai Web SDK 连接选项，例如语音、记忆、传输，以及 `endUserId`.            |
| `客户端`         | `ConvaiClient`                                           | 无                 | 你的应用已创建并连接的客户端。Convai Embody 会基于它驱动唇形同步，并且绝不会断开它。仅在角色创建时读取一次。 |
| `连接`          | `布尔值`                                                    | `true`            | `false` 在没有连接、没有音频、也没有唇形同步的情况下渲染身体。 `客户端` 然后在句柄上 `null`.      |
| `解析器`         | `CharacterResolver`                                      | 基于该凭证构建的 HTTP 解析器 | 自行解析身体清单，适用于私有资源后端、测试夹具或预取的清单。                                |

#### 身体与加载

| 选项                 | 类型                              | 默认值                                                         | 说明                                                                                                |
| ------------------ | ------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `supportedRigs`    | `string[]`                      | `['convai-mha-1']`                                          | 按优先顺序接受的装配配置文件。                                                                                   |
| `dracoDecoderPath` | `string`                        | `'https://www.gstatic.com/draco/versioned/decoders/1.5.7/'` | Draco 解码器的基础 URL。将其设为即可自托管解码器。                                                                    |
| `targetHeight`     | `数字`                            | `1.7`                                                       | 身体缩放到的高度，单位为米。                                                                                    |
| `groundY`          | `数字`                            | `0`                                                         | 脚所放置地面的高度，单位为米。                                                                                   |
| `动画`               | `Record<string, string>`        | 无                                                           | 额外的片段，名称到 URL。按名称与角色自身的片段合并。                                                                      |
| `idleClip`         | `string \| false`               | 名为 `空闲`，否则为第一个片段                                            | 加载时播放的片段。 `false` 以暂停状态开始。                                                                        |
| `faceMaterials`    | `boolean \| FaceMaterialTuning` | `true`                                                      | 对名为以下名称的 MetaHuman 材质进行眼睛、牙齿和眼眶着色： `Eyes*`, `Teeth*`，以及 `Eyeocclusion*`. `false` 将每个材质保持为模型随附的原样。 |
| `装饰器`              | `CharacterDecorator[]`          | 无                                                           | 在加载后、首帧前仅运行一次的函数。                                                                                 |

#### 动作与语音

| 选项        | 类型                | 默认值    | 说明                                    |
| --------- | ----------------- | ------ | ------------------------------------- |
| `动作`      | `布尔值`             | `true` | `false` 关闭注视、呼吸、眼球运动和眨眼，只保留动画片段和唇形同步。 |
| `注视`      | `GazeConfig`      | 内置调优   | 头部和颈部注视跟踪。                            |
| `eyeGaze` | `EyeGazeConfig`   | 内置调优   | 眼球运动。                                 |
| `眨眼`      | `BlinkConfig`     | 内置调优   | 眨眼和眼睑。                                |
| `呼吸`      | `BreathingConfig` | 内置调优   | 胸腔和脊柱的叠加式呼吸。                          |
| `嘴部`      | `MouthTuning`     | 内置调优   | 唇形同步调优，例如下颌张开上限和嘴唇闭合阈值。               |

### CharacterHandle

| 成员       | 类型                          | 说明                                                |
| -------- | --------------------------- | ------------------------------------------------- |
| `根节点`    | `THREE.Object3D`            | 角色。将其添加到你的场景中。                                    |
| `客户端`    | `ConvaiClient \| null`      | 实时的 Convai Web SDK 客户端。 `null` 仅当 `连接` 是 `false`. |
| `camera` | `THREE.Camera \| undefined` | 将其设置为你的相机。没有它，注视跟踪不会起作用。                          |
| `动画`     | `AnimationController`       | 播放并交叉淡化角色的片段。                                     |
| `唇形同步`   | `LipsyncSystem`             | 唇形同步系统。                                           |
| `注视`     | `GazeSystem`                | 头部和颈部注视系统。                                        |
| `bundle` | `CharacterBundle`           | 解析后的身体清单。                                         |
| `表示`     | `Representation`            | 已加载的装配表示。                                         |
| `装配`     | `ResolvedRig`               | 在已加载模型上解析的骨骼和形态目标。                                |
| `管线`     | `Pipeline`                  | 按顺序排列的逐帧系统。                                       |

#### 更新

```typescript
update(delta: number, queue?: BlendshapeQueue): void
```

将角色推进 `delta` 秒。每帧调用一次。 `队列` 用于在一个客户端驱动多个角色时，覆盖身体进行唇形同步的对话轮次。

#### 释放

```typescript
dispose(): void
```

释放模型、材质、纹理和动画混合器。当 Convai Embody 打开的连接会被关闭。通过以下方式传入的客户端 `客户端` 将保持连接状态。

### 错误

| 条件                                    | 结果                                                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 否 `令牌`, `authToken`, `apiKey`，或 `解析器` | 抛出一个错误，其消息以以下内容开头 `@convai/embody: a credential is required`。不会发送任何请求。                                 |
| Convai 无法为该角色解析身体                     | 拒绝并返回 `embodiment resolve failed for <characterId>: HTTP <status>`，后面跟着 Convai 给出的原因，例如 `角色未配置 3D 身体。` |
| 身体在以下位置没有提供装配： `supportedRigs`        | 拒绝并返回 `no supported representation: character offers [<rigs>], embody supports [<rigs>]`               |

### 相关参考

{% content-ref url="/pages/afcae56dd5bee11232aa7e5af42d7608c0a2f044" %}
[React API 参考](/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/createcharacter-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.