> 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
function createCharacter(options: CreateCharacterOptions): Promise<CharacterHandle>
```

### 选项

`characterId` 和一种凭据为必填项。其他所有选项都有可用的默认值。

#### 身份与连接

| 选项            | 类型                                                        | 默认值              | 说明                                                                                                                                                                  |
| ------------- | --------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characterId` | `string`                                                  | 必填               | 要渲染的角色。                                                                                                                                                             |
| `token`       | `string`                                                  | 无                | Convai 身份验证令牌。在浏览器中使用的凭据。其优先级高于 `apiKey`.                                                                                                                           |
| `authToken`   | `string`                                                  | 无                | 与 `token`相同，只是使用 Convai Web SDK 所用的名称。                                                                                                                              |
| `apiKey`      | `string`                                                  | 无                | Convai API 密钥。仅在可信环境中使用。                                                                                                                                            |
| `baseUrl`     | `string`                                                  | 此版本的 Convai 主机   | 后端主机。仅在需要指向其他 Convai 环境时更改。                                                                                                                                         |
| `onPrem`      | `string`                                                  | —                | 本地部署的 Middleman URL（`https://api-<env>.<domain>`）。将 embodiment 清单和角色信息指向该 URL，并派生此部署用于连接的 `live-<env>` 和 `character-apis-<env>` 主机；在 `session` 或 `baseUrl` 中指定的值优先。 |
| `session`     | `SessionOptions` 不包含 `characterId`, `apiKey`, `authToken` | 无                | 其他 Convai Web SDK 连接选项，例如语音、记忆、传输方式和 `endUserId`.                                                                                                                   |
| `client`      | `ConvaiClient`                                            | 无                | 应用已创建并连接的客户端。Convai Embody 会用它驱动口型同步，且绝不会断开它。此选项只会在创建角色时读取一次。                                                                                                       |
| `connect`     | `boolean`                                                 | `true`           | `false` 会在不建立连接、不播放音频且不同步口型的情况下渲染身体模型。 `client` 在句柄上随后为 `null`.                                                                                                     |
| `resolver`    | `CharacterResolver`                                       | 根据凭据构建的 HTTP 解析器 | 自行解析主体清单：可以是你托管的模型、私有资源后端、测试样例或预取的清单。请参阅 [解析器和主体清单](#resolvers-and-the-body-manifest).                                                                              |

#### 主体与加载

| 选项                 | 类型                                          | 默认值                                                         | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `supportedRigs`    | `string[]`                                  | `['convai-mha-1']`                                          | 按优先顺序排列的可接受骨架配置。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `modelVariant`     | `'auto' \| 'full' \| 'lite'`                | `'auto'`                                                    | 当主体同时提供 Full 和 Lite 文件时，要加载的模型文件。 `'auto'` 在手机、平板以及 GPU 性能不足以处理 Full 的混合形状的设备上加载 Lite，其他设备则加载 Full。                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `dracoDecoderPath` | `string`                                    | `'https://www.gstatic.com/draco/versioned/decoders/1.5.7/'` | Draco 解码器的基准 URL。设置此项可自行托管解码器。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `targetHeight`     | `number`                                    | `1.7`                                                       | 主体缩放后的高度，单位为米。在模型加载时测量一次。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `groundY`          | `number`                                    | `0`                                                         | 脚底所踩地面的高度，单位为米。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `grounding`        | `'feet' \| 'clip'`                          | `'feet'`                                                    | `'feet'` 每帧都让任一脚底的最低点保持在地面上。 `'clip'` 将主体放置在地面上一次，之后由动画决定其高度，适用于跳跃。                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `animations`       | `Record<string, string>`                    | 无                                                           | 额外动画片段，键为名称，值为包含同名动画的 GLB、glTF 或 FBX 文件的 URL。来自 Mixamo 或 Rigify 骨架的片段会在加载时重定向到主体。按名称与角色自带的片段合并。角色创建时读取一次。请参阅 [添加自定义动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md).                                                                                                                                                                                                                                                                                                   |
| `idleClip`         | `string \| false`                           | 名为 `idle`的片段；否则使用第一个片段                                      | 加载时播放的片段。 `false` 将以暂停状态启动。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `faceMaterials`    | `boolean \| FaceMaterialTuning`             | `true`                                                      | 让眼睛和牙齿在任何光照下都显得栩栩如生。眼球（任何名称中包含 eye 的材质）会变得湿润有光泽，并呈现清晰的虹膜、深色瞳孔，以及在角膜上反射的眼部高光（`catchlight`，设为 0 可关闭）。牙齿（`Teeth*`) 会被周围的口腔照亮并产生阴影，因此不会在黑暗的口腔中发光。MetaHuman 眼窝遮挡膜（`Eyeocclusion*`) 只会使其变暗。 `false` 会保留模型原有的所有材质。                                                                                                                                                                                                                                                                                                                              |
| `surfaces`         | `boolean \| SurfaceTuning`                  | `true`                                                      | 用于皮肤和头发的着色，让身体对场景光照的反应符合皮肤和头发的真实表现。皮肤采用基于物理的着色，光线会柔和地延伸到阴影边缘之外；在 WebGL 渲染器中还会呈现毛孔细节。头发和睫毛以柔和且按深度排序的边缘绘制；头发靠近头皮处颜色较深，浅色头发会显示不带颜色的高光；头发下方的头皮会以头发的颜色着色，并且纹理会进行各向异性采样。不会更改你的灯光。清单中标记为 `gender: 'male'` 的角色会呈现男性外观：睫毛使用纹理自身的 alpha 值，皮肤反应更紧致、粉色更少，毛孔细节更多，光照包裹效果更弱。 `false` 会保留模型原有的所有皮肤和头发材质。 `SurfaceTuning` 用于调整 `skin` (`SkinTuning`: `roughness`, `sheen`, `sheenColor`, `specular`, `tint`, `detail`, `wrap`, `subsurface`, `translucency`, `shadowFloor`), `hair`, `scalp`, `anisotropy`, `gender` 和 `lashOpacity`；你设置的任何值都会覆盖男性外观的默认值。 |
| `morphMap`         | `'auto' \| false \| Record<string, string>` | `'auto'`                                                    | 使用其他名称的面部形状。口型同步、眨眼和眼球运动会使用 MetaHuman 表情通道（`jawOpen`, `eyeBlinkL`、……）；此映射可将通道对应到模型自身的变形名称。 `'auto'` 会按含义查找形状：重命名或带前缀的 MetaHuman 形状、Character Creator 的扩展形状集，以及 52 个 ARKit 形状。当前生效的映射位于 `character.report.face.morphMap`中，可复制粘贴回此处以固定或修正映射。                                                                                                                                                                                                                                                                                               |
| `diagnostics`      | `boolean`                                   | `true`                                                      | 当模型出现错误或警告时，将 `character.report` 输出到控制台，其中每项都会说明可修复问题的配置或导出更改。                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `decorators`       | `CharacterDecorator[]`                      | 无                                                           | 加载后、首帧之前运行一次的函数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### 动作与语音

| 选项              | 类型                | 默认值    | 说明                                                                                                                                                                                                                                                              |
| --------------- | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `motion`        | `boolean`         | `true` | `false` 关闭视线追踪、呼吸、眼球运动和眨眼，仅保留动画片段和口型同步。                                                                                                                                                                                                                         |
| `gaze`          | `GazeConfig`      | 内置调节项  | 头部、颈部和躯干的视线追踪。 `lookAways: false` 停止视线移开的动作， `torso: false` 让躯干保持静止，而 `headLimit` 设置头部转动的幅度。                                                                                                                                                                    |
| `eyeGaze`       | `EyeGazeConfig`   | 内置调节项  | 眼球运动。通过测量身体自身的眼睛形状，让每只眼睛都朝向摄像机；保持目光接触时，眼睛会有轻微的扫视。 `saccades: false` 让眼睛保持静止。没有摄像机或角色没有注意目标时，眼睛会保持上次注视方向的世界坐标方向——头部转动时，眼睛会在同一帧内作出补偿——随后在约半秒内逐渐转向头部正前方，而不是跟着头部转动。                                                                                                 |
| `blink`         | `BlinkConfig`     | 内置调节项  | 眨眼和眼睑。一次眨眼取自 36 段录制动作之一——上下眼睑各自沿曲线运动，完整保留双眨眼——按录制时的 60 Hz 时间播放，因此任何帧率下呈现的形状都相同，并进行缩放，使幅度最大的一次眨眼能完全闭合眼睑。眨眼时序、局部眨眼、双眨眼以及静息时的眼睑下垂均由 embody 自行处理； `asymmetry` （默认值为 0.3）表示眼睑保留录制动作中左右差异的程度。 `envelope: 'procedural'` 保留早期版本的正弦/余弦包络； `enabled: false` 将眼睑控制权交给动画。   |
| `breathing`     | `BreathingConfig` | 内置调节项  | 为胸部和脊柱添加叠加式呼吸动作。                                                                                                                                                                                                                                                |
| `morphNormals`  | `boolean`         | `true` | 对于只提供混合形状位置、未提供混合形状法线的模型（所有已发布的 MetaHuman 身体模型均如此），在面部混合形状产生位移的位置重新计算表面法线。否则，闭合的眼睑仍会使用睁眼时的法线进行光照计算，导致阴影发黑。此计算是稀疏的：仅处理形状发生位移的顶点，并且只在权重变化时进行。                                                                                                                     |
| `mouth`         | `MouthTuning`     | 内置调节项  | 口型同步调节项。嘴部跟随语音自身的播放时钟；发出 m、b、p 音时闭合双唇，在语音停顿时放松，在回复结束时闭合一次，并在句子之间保持静息表情。 `expression` 设置该表情的情绪（`'neutral'`, `'warm'`, `'curious'`, `'focused'`，或 `'steady'`，男性身体的默认值：眉毛略微下压且不微笑），或使用 `false`. `voiceLeadSeconds` 设置嘴部动作领先语音的时长，而 `finish: false` 关闭闭合动作、暂停和柔化效果。 |
| `correctiveMap` | `CorrectiveMap`   | 无      | 一个由 `compileCorrectiveMap`构建的表，用于重新加权每一帧唇形同步，使其更贴近完整骨架。适用于每个控制项只驱动一个变形目标的身体模型；这类模型不会呈现骨架的任何修正形状或关节运动。你可以随时通过 `handle.lipsync.correctiveMap`.                                                                                                                    |

### 角色句柄

| 成员               | 类型                          | 说明                                                                                                               |
| ---------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `root`           | `THREE.Object3D`            | 角色。将其添加到场景中。                                                                                                     |
| `client`         | `ConvaiClient \| null`      | 实时 Convai Web SDK 客户端。 `null` 仅当 `connect` 为 `false`.                                                            |
| `camera`         | `THREE.Camera \| undefined` | 将此项设为你的摄像机。没有摄像机时，注视跟踪不会运行。                                                                                      |
| `animations`     | `AnimationController`       | 播放角色动画片段并在片段间交叉淡化。请参阅 [AnimationController](#animationcontroller).                                               |
| `model`          | `ModelVariant`              | 已加载的模型文件，取值为以下之一： `representation.model`.                                                                        |
| `lipsync`        | `LipsyncSystem`             | 唇形同步系统。设置 `lipsync.expression.mood` 即可在角色运行时更改其静止表情。                                                             |
| `gaze`           | `GazeSystem`                | 注视系统。 `focus` 是角色注视的点，而 `setEnabled(false)` 会将头部控制权交还给动画。                                                        |
| `bundle`         | `CharacterBundle`           | 解析后的身体清单。                                                                                                        |
| `representation` | `Representation`            | 已加载的骨架表示。                                                                                                        |
| `rig`            | `ResolvedRig`               | 在已加载模型上解析出的骨骼和变形目标。                                                                                              |
| `pipeline`       | `Pipeline`                  | 按顺序排列的逐帧系统。                                                                                                      |
| `report`         | `CharacterReport`           | 说明加载的模型能够和不能够执行的操作：生效的面部命名和形态映射、眨眼和眼球运动、骨架、所有动画片段，以及每个问题及其修复方法。同一份报告 `inspectModel(url, options)` 会返回报告，但不会创建角色。 |

#### 更新

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

将角色推进 `delta` 秒。每帧调用一次。 `queue` 可指定身体口型同步所对应的对话轮次，适用于一个客户端驱动多个角色的情况。

#### 释放

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

释放模型、材质、纹理和动画混合器。如果连接是由 Convai Embody 打开的，则关闭该连接。通过 `client` 传入的客户端会保持连接。

### 动画控制器

`character.animations` 用于播放角色的动画片段，一次播放一个，并在片段之间进行混合。

| 成员                            | 类型                                                                                    | 说明                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `names`                       | `string[]`                                                                            | 角色拥有的所有动画片段。                                             |
| `playing`                     | `string \| null`                                                                      | 当前正在播放的动画片段。                                             |
| `play(name)`                  | `(name: string) => void`                                                              | 从第一帧开始播放动画片段并循环，不进行混合。                                   |
| `crossfadeTo(name, options?)` | `(name: string, options?: ClipTransition) => void`                                    | 从当前动画片段混合过渡到 `name`。如果 `name` 已经在播放，则不执行任何操作。            |
| `register(clips)`             | `(clips: THREE.AnimationClip[]) => { name: string; kept: number; dropped: number }[]` | 添加动画片段，例如已加载的 GLB 中的 `animations` 。模型中不存在对应骨骼的轨道会被丢弃并报告。 |
| `mixer`                       | `THREE.AnimationMixer`                                                                | 底层动画混合器。                                                 |

`ClipTransition`:

| 字段           | 类型        | 默认值     | 说明                      |
| ------------ | --------- | ------- | ----------------------- |
| `duration`   | `number`  | `0.35`  | 混合时长，单位为秒。              |
| `once`       | `boolean` | `false` | 仅播放一次，并停留在最后一帧，而不是循环播放。 |
| `thenBackTo` | `string`  | 无       | 与 `once`，片段结束时过渡到此片段。   |

`play` 和 `crossfadeTo` 对于角色没有的名称会抛出错误。Convai Embody 不会在角色说话时切换片段；请监听客户端的 `speakingChange` 事件来执行此操作，如 [添加自定义动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md#switch-to-a-talking-clip-while-the-character-speaks).

### 解析器与 body manifest

一个 `CharacterResolver` 只有一个方法： `resolve(characterId: string): Promise<CharacterBundle>`。默认解析器 `httpResolver({ baseUrl?, apiKey?, authToken? })`会向 Convai 发起请求。要加载自行托管的模型，请提供自定义解析器；请参阅 [使用自己的 3D 模型](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/use-your-own-3d-model.md).

`CharacterBundle`:

| 字段                | 类型                 | 说明                                        |
| ----------------- | ------------------ | ----------------------------------------- |
| `characterId`     | `string`           | 此 manifest 对应的角色。                         |
| `avatarId`        | `string`           | 用于标识身体。                                   |
| `gender`          | `string`           | 可选。Convai 报告的身体性别。                        |
| `fallback`        | `boolean`          | 可选。 `true` 表示角色没有自己的身体，因此 Convai 提供了默认身体。 |
| `thumbnail`       | `string`           | 可选。身体的图像。                                 |
| `representations` | `Representation[]` | 为其构建该身体的各个骨架配置。                           |

`Representation`:

| 字段      | 类型                                | 说明                                                                                                                                                |
| ------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rig`   | `string`                          | 骨架配置；对于 MetaHuman 身体， `'convai-mha-1'` 即为其配置。                                                                                                     |
| `model` | `ModelVariant[]`                  | 模型文件： `{ url, lod?, morphTargets?, size? }`. `lod` 0 表示 Full，1 表示 Lite； `morphTargets` 表示任一网格上的最大混合变形数量，该值 `modelVariant: 'auto'` 会与 GPU 的限制进行比较。 |
| `clips` | `Record<string, { url: string }>` | 可选。将片段名称映射到包含同名动画的 GLB 文件。                                                                                                                        |

在 React 中，解析器是角色身份标识的一部分：新的解析器对象会重新加载模型。请在组件外定义解析器，或使用 memoize 将其缓存。

### 错误

| 条件                                            | 结果                                                                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 否 `token`, `authToken`, `apiKey`，或 `resolver` | 抛出一条错误消息以以下内容开头的错误 `@convai/embody: a credential is required`。不会发送请求。                                                                 |
| Convai 无法解析角色的身体                              | 拒绝，并返回 `embodiment resolve failed for <characterId>: HTTP <status>`，后面跟着 Convai 给出的原因，例如 `Character has no 3D embodiment configured.` |
| 身体在 `supportedRigs`                           | 拒绝，并返回 `no supported representation: character offers [<rigs>], embody supports [<rigs>]`                                             |
| `play` 或 `crossfadeTo` 并使用角色不具备的片段            | 抛出 `[embody] unknown clip "<name>" (have: <names>)`                                                                                   |

### 相关参考

{% 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/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.
