UNITH 数字人技能

使用 UNITH API 创建、配置、更新和部署 AI 驱动的数字人形象（Digital Human avatar）。

快速概览

UNITH 数字人是具备语音输出、自然对话与用户交互能力的 AI 形象。它将面部（头部视觉效果）、语音和对话引擎三者整合，提供托管式、可嵌入的完整体验。

基础 API 地址：https://platform-api.unith.ai
文档：https://docs.unith.ai

前提条件

用户需提供以下凭据（以环境变量形式存储）：

⚠️ 密钥仅在生成时显示一次。若丢失，用户需删除并重新生成。

身份验证

所有 API 请求均需携带 Bearer Token（有效期为 7 天）。请使用认证脚本：

source scripts/auth.sh

该脚本会校验凭据，在网络错误时自动重试，并导出环境变量 UNITH_TOKEN。若失败，将输出具体错误提示（如密钥错误、Token 过期等）。

工作流：创建数字人

步骤 1：选择运行模式

向用户询问其希望数字人实现的功能，并据此映射至以下 5 种模式之一：

复杂度光谱（由简至繁）：

• 最简单：ttt — 输入文本即输出视频，无需知识库。
• 标准型：oc — 基于系统提示词的通用对话助手，适用于通用助理场景。
• 知识增强型：doc_qa — 上传文档后，数字人仅依据文档内容作答，适用于客服/FAQ 场景。
• 流程驱动型：voiceflow — 支持预设对话路径的结构化交互，需拥有 Voiceflow 账户。
• 最灵活型：plugin — 用户自定义对话引擎（BYO），提供最高控制权。

步骤 2：列出可用面部资源

bash scripts/list-resources.sh faces

每个面部资源具有唯一 id（创建数字人时用作 headVisualId）。面部类型包括：

• 公开（Public）：所有组织均可使用
• 私有（Private）：仅限用户所属组织使用
• 自定义（BYOF）：用户上传真人视频（当前由 UNITH 后台管理）

请向用户展示可用面部列表，并由其选择。

步骤 3：列出可用语音资源

bash scripts/list-resources.sh voices

语音由不同服务商提供：elevenlabs、azure、audiostack。请向用户呈现可选语音列表。语音按性能分级——响应更快的语音更适合实时对话场景。

步骤 4：创建数字人

构建 JSON 负载文件（各模式的具体 schema 参见 references/api-payloads.md），然后执行：

bash scripts/create-head.sh payload.json --dry-run   # 先验证格式
bash scripts/create-head.sh payload.json              # 正式创建

该脚本将校验必填字段、检查模式特定要求、在服务端错误时自动重试，并在成功后打印 publicUrl。

步骤 5（仅 doc_qa 模式）：上传知识文档

对于 doc_qa 模式，数字人需关联一份知识文档：

bash scripts/upload-document.sh  /path/to/document.pdf

该脚本会校验文件是否存在及大小是否合规，对上传操作启用更长超时时间，并提供后续操作指引。

步骤 6：测试与迭代

数字人将在步骤 4 输出的 publicUrl 上线运行。用户应执行以下操作：

1. 访问该 URL 并测试对话功能
2. 按需更新配置（详见下文）

更新数字人

使用更新脚本修改任意参数（除面部外；更换面部需新建数字人）：

bash scripts/update-head.sh  updates.json                         # 从 JSON 文件批量更新
bash scripts/update-head.sh  --field ttsVoice=rachel              # 单字段更新
bash scripts/update-head.sh  --field ttsVoice=rachel --field greetings="Hi!"  # 多字段更新

列出已有数字人

bash scripts/list-resources.sh heads           # 列出全部数字人
bash scripts/list-resources.sh head    # 获取指定数字人详情

删除数字人

bash scripts/delete-head.sh  --confirm     # 在自动化/Agent 场景中务必使用 --confirm

此操作将永久删除数字人，不可撤销。

Agent 注意事项：调用该脚本时必须始终传入 --confirm 参数。否则脚本将等待交互式确认输入，导致阻塞。

嵌入使用

数字人支持嵌入网站或应用程序。嵌入代码片段与配置选项详见 references/embedding.md。

脚本说明

所有脚本均内置重试机制（指数退避）、清晰的错误信息及输入校验逻辑。

可通过环境变量配置行为：

• UNITH_MAX_RETRIES — 最大重试次数（默认值：3）
• UNITH_RETRY_DELAY — 首次重试前等待秒数（默认值：2，每次重试翻倍）
• UNITH_CURL_TIMEOUT — curl 请求超时时间（单位：秒，默认值：30；上传时为 120）
• UNITH_CONNECT_TIMEOUT — 连接超时时间（单位：秒，默认值：10）
• UNITH_TOKEN_CACHE — Token 缓存文件路径（默认值：/tmp/.unith_token_cache；设为空字符串可禁用缓存）

详细 API 参考

关于完整负载结构、全部可配置参数及各模式特性的说明，请参阅：

阅读 references/api-payloads.md      # 各模式的完整请求/响应结构定义
阅读 references/configuration.md     # 所有可配置参数说明
阅读 references/embedding.md         # 嵌入代码与配置选项

常见使用模式

“我想快速生成一段某人说 X 内容的视频” → 使用 ttt 模式，配置极简
“我想打造一个客服数字人” → 使用 doc_qa 模式并上传知识文档
“我想部署一位 AI 销售代表” → 使用 oc 模式，并配置销售风格的系统提示词
“我想接入我自己的大语言模型” → 使用 plugin 模式并提供 Webhook URL
“我想实现引导式新手入门流程” → 使用 voiceflow 模式并提供 Voiceflow API Key

需向用户收集的信息

创建前，请向用户确认以下信息：

1. 用途 / 使用场景 → 决定运行模式
2. 面部偏好 → 提供可用面部列表供其选择
3. 语音偏好 → 语言、口音、性别、语速优先级等
4. 别名 → 数字人的显示名称
5. 语言 → 语音识别与界面语言（例如：en-US、es-ES）
6. 欢迎语 → 数字人首次启动时说出的内容
7. 系统提示词（适用于 oc/doc_qa 模式）→ 定义数字人人格与行为规范
8. 知识文档（适用于 doc_qa 模式）→ 待上传的文件
9. Voiceflow API Key（适用于 voiceflow 模式）→ 来自其 Voiceflow 账户
10. 插件 URL（适用于 plugin 模式）→ 自定义对话引擎的 Webhook 终端地址