3 分钟接入数字角色

快速开始

三步接入：引入 SDK → 加载角色 → 调用 API。下面这段现在就能跑（把 embed_xxx 换成你在接入向导生成的嵌入 Token）。

<!-- Step 1: 引入浏览器 SDK（平台内直接引用；npm 包计划 V1.0 发布）-->
<script src="https://hwavatar.com/assets/js/digitalpet-sdk.js"></script>

<script>
// Step 2: 初始化 SDK 并加载角色到指定容器
const pet = new DigitalPetSDK({
  token: 'embed_xxx',                   // 嵌入 Token，不暴露账户级 API Key
  endpoint: 'https://api.hwavatar.com'
});

await pet.loadCharacter('char_xxx', {
  container: document.getElementById('pet-container'),
  width: 320, height: 480
});

// Step 3: 驱动角色说话（服务端豆包 TTS，音色跟随角色配置）
await pet.speak('你好，很高兴认识你！');

// 对话 + 播报：调 /api/chat 流式拿回复，再自动 TTS
await pet.chatAndSpeak('你今天心情怎么样？');
</script>

认证方式

内测期鉴权（当前可用）

三种真实凭证，统一放在 Authorization: Bearer <凭证> 请求头；浏览器第一方页面也可用登录 Cookie（session）。

未携带凭证时，仅第一方页面（/demo、/desktop-pet）与本地文件页放行，其余返回 401；默认限流 30 次/分钟，超限返回 429 与 Retry-After。

AK/SK 签名（V1.0 开放）

复用 B 端 AK/SK + HMAC-SHA256 签名机制，与阿里云 ACS3、腾讯云 TC3 风格一致，便于 B 端客户无缝迁移；V1.0（2026.11）开放后 API Key 仍可继续使用。

签名流程

1. 构造 CanonicalRequest = HTTPMethod + URI + QueryString + Headers + BodyHash
2. StringToSign = "DPAPI-HMAC-SHA256\n" + Timestamp + "\n" + HEX(SHA256(CanonicalRequest))
3. Signature = HEX(HMAC-SHA256(SecretKey, StringToSign))
4. Authorization: DPAPI-HMAC-SHA256 Credential={AK},SignedHeaders={headers},Signature={sig}
5. 服务端验签：校验 x-dp-date 是否在 15 分钟窗口内，并检查 x-dp-nonce 是否已被使用

防重放要求：SignedHeaders 必须包含 x-dp-date 与 x-dp-nonce，二者参与签名计算；服务端需维护 nonce 去重存储（TTL ≥ 15 分钟），重复 nonce 直接返回 401。若 nonce 不参与签名，攻击者可原样重放已抓取的请求。

客户端密钥安全

SecretKey 是账户级凭据，严禁写入前端代码、客户端包或浏览器环境。Web / 移动端应由业务服务端用 SK 签名，或先换取短期、限定角色与配额的访问令牌（token）再下发给客户端。

必要请求头

SDK 下载

<script src="https://hwavatar.com/assets/js/digitalpet-sdk.js"></script>

npm i @digitalpet/web-sdk   （计划 V1.0）

当前 SDK 提供 loadCharacter()、speak()、chat()、chatAndSpeak()、startSession()、stop() 与 ready / speaking / reply / idle / error 事件。本地定时任务与动作触发（triggerAction()）后续补齐；角色状态（饱腹感 / 心情值 / 亲密度）后续随角色状态系统接入云端同步。

角色管理

下列 /v1/* 为对外正式 API（分页、筛选、模型包签名下载），随 V1.0 发布。

播报服务

下列 /v1/* 为对外正式 API（含流式分帧与口型数据），按版本计划发布；内测期可直接调用的是 /api/tts（播报）、/api/chat（对话，流式纯文本）、/api/characters（角色列表）。

{"type":"audio","seq":0,"data":"base64…","sample_rate":16000}
{"type":"lipsync","seq":0,"visemes":[{"t":0,"v":"A","w":0.8},{"t":80,"v":"O","w":0.6}]}
{"type":"end","total_duration":2.5,"total_visemes":32}

实时对话 规划中

下列 /v1/sessions 为对外正式 API（含人设配置、记忆窗口、知识库与实时长连接），后续发布。

{
  "character_id": "char_xxx",
  "persona": {
    "name": "示例角色",
    "personality": "活泼开朗、喜欢交朋友",
    "knowledge_base": ["kb_001", "kb_002"]
  },
  "voice_id": "zh_female_tianmeixiaoyuan_uranus_bigtts",
  "memory_window": 20,
  "language": "zh-CN"
}

动作 / 表情 规划中

用量查询

下列 /v1/* 为对外正式 API（AK/SK 认证，可查历史账期与账户余额），随 V1.0 发布；内测期请用 GET /api/auth/me。

WebSocket 协议

实时场景使用 WebSocket 长连接，通道内 JSON 消息帧通信：

口型数据规范

采用 Viseme 格式，每个包含音素类别、时间戳（t，毫秒）、强度（w，0.0-1.0）。下表是唯一规范来源，取值一律大写（SDK、演示页、示例数据都以它为准），共 12 个类别：

Webhook 回调 规划中

注册回调 URL，事件发生时主动推送 HTTP 请求。

服务状态

以上状态由服务端实时检查依赖配置与数据可读性生成，不展示历史可用率。V1.0 公测阶段不提供赔付性 SLA，正式商用版本将启用独立状态页与可用率历史。

更新日志

合规说明

本产品属于生成式人工智能与深度合成服务，正式上线版本将按《生成式人工智能服务管理暂行办法》《互联网信息服务深度合成管理规定》《个人信息保护法》等要求交付：

• AI 生成内容标识：视频合成输出加 AIGC 水印，实时对话在角色旁显示 AI 标识，API 响应包含 AIGC 标记字段
• 深度合成备案与算法备案：生成式人工智能服务备案与深度合成算法备案正在办理，完成后在本页公示备案编号
• 经营主体：深圳幻维科技有限公司，统一社会信用代码与营业执照可在关于我们页面查看
• 数据隐私：对话数据加密存储，用户可一键清除历史；未经明确授权不用于模型训练
• 内容安全：TTS 文本与 LLM 回复均经过内容安全过滤，角色上架前经自动 + 人工审核
• 未成年人保护：企业版支持年龄验证与家长管控接口，人设禁止不当内容

V1.0 公测阶段，AIGC 标识与内容安全过滤已启用；备案类资质仍在办理中，取得编号后即时在本页与关于我们页面更新。

版本与限流

接口版本通过路径区分（当前为 /v1），版本内只做向后兼容的新增，不改变既有字段语义。废弃字段会先在响应头 Deprecation 中标注，并至少保留 6 个月，旧版本下线前 30 天在本页与更新日志公示。

并发超限返回 429（错误码 concurrency_exceeded），客户端应退避重试；单账号另有每分钟请求数限制，默认 60 次/分钟，超限返回 429 并带 Retry-After。

联系我们

企业定制、版权买断与商务合作：请通过定制服务页面提交需求；开发者在接入过程中遇到问题，可登录后在 /support 提交工单，客服会在站内回复并跟进处理。

• 微信扫右侧二维码添加（工作日 10:00 - 19:00）
• 邮箱sales@hwavatar.com（商务） · support@hwavatar.com（售后，1 个工作日内回复）
• 开票默认增值税普通发票；专用发票需提供一般纳税人资质，随订单邮件申请
• 对公企业采购支持对公转账与合同签署，账户与合同模板由商务对接时提供
• 地址广东省深圳市宝安区新安街道大宝路一巷 2-3 号友谊大厦 A-1

用户服务协议

生效日期：2026 年 11 月 1 日 · 版本 v1.0 · 提供方：深圳幻维科技有限公司

本协议是你与深圳幻维科技有限公司（下称「我们」）之间关于使用幻维平台（域名 hwavatar.com 及其子域，下称「本服务」）的约定。注册、开通套餐、调用 API 或使用客户端，即表示你已阅读并同意本协议。

一、账号与凭证

• 你应使用真实、准确的信息注册，并对账号下的全部操作承担责任。
• API Key、Embed Token 仅限你自己或你所在组织内部使用，不得转售、公开或用于搭建与本服务实质竞争的镜像服务。
• 发现凭证泄露应立即在控制台吊销并重新生成；因你保管不当造成的损失由你自行承担。

二、授权范围

• 免费版：仅限个人学习、测试与非商业用途，不得用于任何直接或间接获利的场景，包括但不限于为客户交付、付费产品内嵌、商业宣传物料。
• 付费版：在订阅有效期与所选档位范围内授予商业使用权，你可将本服务生成的语音、视频与对话内容用于自用或交付给客户。授权随订阅终止而终止，已交付的成品可继续使用。
• 角色形象、模型、动作与音色等资产的知识产权归我们或原始权利人所有。你不得提取、复刻、注册为商标，或用于训练与本服务同类的模型。
• 如需独占授权、买断或二次分发，须另行签署书面协议。

三、AI 生成内容标识（重要）

• 依据《人工智能生成合成内容标识办法》等规定，本服务输出的视频、音频与对话在生成时带有显式或隐式的 AI 生成标识。
• 你不得以任何方式去除、遮挡、篡改或规避这些标识，也不得在传播时声称内容完全由真人创作。此条为实质条款，违反将被立即暂停服务并追究责任。
• 你在对外发布生成内容时，应自行依法添加相应标识，并确保不误导公众。

四、使用规范

• 禁止用于违法犯罪、危害国家安全、淫秽色情、暴力恐怖、赌博、诈骗、虚假信息传播等用途。
• 禁止未经本人明确同意，使用他人肖像、姓名、声音或身份进行深度合成、冒充或误导性表达。
• 禁止生成侵犯他人知识产权、名誉权、隐私权的内容，或用于骚扰、歧视、未成年人伤害场景。
• 你对通过本服务输出与传播的全部内容承担责任。我们有权在发现违规时暂停或终止服务，并依法配合主管部门处置。

五、额度、计费与退款

• 各档位的月度积分按自然月重置；语音 1 秒 / 对话 1 次 = 1 积分，视频导出 1 条 = 100 积分。超出部分按定价页公示的单价计费，用尽后接口返回明确错误码，不会静默扣费。
• 升级即时生效并重新计算本期积分；降级于本期结束后生效。
• 本服务属按需提供的虚拟服务。订阅开通后 7 日内且已用积分低于当期总额度 10% 的，可申请退还未使用部分；已产生的用量对应的费用不予退还。
• 角色券是独立于套餐积分的虚拟凭证，不随账期重置、永不过期，仅用于永久解锁付费角色，不能兑换现金或转让。角色券一经充值、角色解锁成功后，均不支持退款。
• 企业版按合同约定执行，不适用「不限量」承诺，均为基准额度加超额单价。

六、服务可用性与变更

• 当前处于内测与公测阶段，不对免费版及内测能力承诺 SLA；付费档位的可用性承诺以各档位页面公示内容为准。
• 因第三方模型、语音或支付服务中断、网络故障、不可抗力导致的中断，我们不承担违约责任，但会尽力恢复并相应补偿额度。
• 我们可能调整功能、额度或价格，调整前将在本页公示；已生效的订阅周期内不做不利变更。

七、责任限制

• 本服务按「现状」提供。对因使用生成内容产生的商业损失、第三方索赔，由你自行承担。
• 在法律允许的最大范围内，我们对你的赔偿责任总额不超过你在索赔发生前 12 个月内为本服务实际支付的费用；免费版用户上限为人民币 100 元。
• 我们不对生成内容的准确性、完整性、合法性作出保证，请在使用前自行审核。

八、终止与协议更新

• 你严重违反本协议（尤其是第三条标识条款与第四条使用规范）的，我们可立即停止服务，已支付费用不予退还。
• 你可在控制台停止使用并申请注销账号；注销后我们按隐私政策处理你的数据。
• 本协议更新时将在本页公示，公示 7 日后生效；继续使用即视为接受更新后的版本。

九、法律适用

本协议适用中华人民共和国法律。因本协议产生的争议，双方应友好协商；协商不成的，提交深圳市有管辖权的人民法院处理。

联系邮箱 sales@hwavatar.com（商务） · support@hwavatar.com（售后） · 也可扫码添加右侧微信

隐私政策

生效日期：2026 年 11 月 1 日 · 版本 v1.0

我们依据《个人信息保护法》《网络安全法》等规定处理你的个人信息。本政策说明我们收集什么、如何使用、与谁共享，以及你享有的权利。

一、我们收集的信息

• 账号信息：用户名、密码（仅以哈希形式存储）、邮箱、手机号。
• 交易信息：订单号、套餐、金额、支付状态。支付由微信支付等第三方处理，我们不收集银行卡号。
• 使用信息：API 调用时间、角色标识、积分消耗明细、错误码、IP 地址与设备标识。
• 内容数据：你提交的对话文本、合成文本，以及你在创作或上传功能中提交的素材。

二、使用目的

• 提供、维护与计费本服务，生成你请求的语音、对话与视频。
• 进行内容安全审核，防止违法违规与滥用行为。
• 排查故障、保障安全、履行法定义务与配合监管要求。

三、第三方共享

为完成你请求的功能，必要信息会传输给以下服务商，仅在实现功能所必需的范围内共享：

• 大模型推理服务（DeepSeek）：接收对话文本以生成回复。
• 火山引擎（豆包语音合成）：接收待合成文本与音色参数以生成音频。
• 腾讯云：服务器与存储资源，数据存储于中华人民共和国境内。
• QQ 邮箱：发送验证码与通知邮件。
• 微信支付：处理订单支付与对账。

我们不出售你的个人信息，也不会将你的对话与生成内容用于训练模型。

四、存储与期限

• 数据存储于境内服务器；不进行跨境传输。
• 调用日志与内容审计记录按需要保存，最长不超过 90 天；订单与计费记录按法律法规要求长期保存。
• 视频合成结果默认保存在你的本机浏览器（IndexedDB），不上传服务器；清除浏览器数据即删除。

五、本机存储

登录凭证保存在浏览器本地存储（localStorage），本机视频历史保存在 IndexedDB。这两项数据仅存在你的设备上，我们无法读取，也不随账号同步到其他设备。

六、你的权利

• 你可以查询、更正账号信息；如需删除对话记录、导出数据或注销账号，可通过下方方式提出申请。
• 你可以申请导出或删除个人信息、注销账号。注销后除法律要求保留的信息外，我们将删除或匿名化处理。
• 你可以撤回授权或拒绝非必要信息的处理，但可能影响部分功能使用。
• 行使上述权利请发送邮件至 support@hwavatar.com，我们将在核验身份后处理。

七、未成年人

本服务面向成年人提供。未满 18 周岁的使用者应在监护人同意与指导下使用；我们不为未满 14 周岁的儿童提供本服务。

八、安全措施

全站启用 HTTPS 传输，密钥仅在服务端保存与使用，管理后台设有访问控制与操作留痕。发生个人信息安全事件时，我们将依法通知你并向主管部门报告。

九、政策更新

本政策更新将在本页公示；重大变更会通过站内通知或邮件告知。如有疑问，请联系 support@hwavatar.com。