01正在检查
资源管理令牌
角色、预览、资源下载和服务设置使用同一管理鉴权。
Authorization: Bearer <管理令牌>读取 /api/bootstrap 的 auth_required。DIMENSOUL / API REFERENCE
在线接入指南小程序与设备 API 文档
角色目录、板端资源与主播版 OTA 的接入说明。先确认地址和鉴权，再按设备与小程序的分工完成联调。
13 个接口入口3 类独立凭据JSON · TSV · 二进制
查看接口 角色与小程序
读取角色目录，生成资源预览。
板端资源
清单比对、下载与完整性校验。
主播版 OTA
设备签名、检查更新与下载。
先确认连接条件
地址与鉴权
当前后台地址
正在读取当前页面地址…下方管理接口示例使用当前后台地址。设备地址请使用 设备更新中配置的检查地址，并从设备所在 Wi-Fi 验证可达；电脑能通过 Tailscale 访问，不代表设备也能访问。
02正在检查
主播版运维会话
开启登录的部署使用独立运维账号，管理登记、上传和发布。
独立于资源管理令牌读取 /api/creator-ota/auth-config 的 required。03始终需要
设备出厂密钥
设备检查和固件下载按每台设备的独立密钥计算 HMAC。
X-Device-Signature内网免登录不会关闭设备签名验证。正在检查当前部署的管理访问要求…
ENDPOINT REFERENCE
接口参考
展开接口查看字段与示例。所有示例均为结构说明，示例名称、地址、密钥与校验值需要替换。
没有找到匹配的接口
试试「角色」「manifest」「签名」或接口路径。
MINIAPP → DEVICE → SERVER
一次 OTA，如何完成
以下四个名称属于小程序与设备之间的 BLE 命令契约，不是服务器 HTTP 接口。服务器提供候选固件和下载，安装由用户在小程序中明确发起。
- 1
配置服务
set_service_config小程序向设备写入设备可达的服务地址。设备发送已签名的
intent=bootstrap请求，读取时间与连接信息；此时firmware=null。 - 2
检查更新
check_ota设备向
POST /v1/device/ota发送intent=check_ota，查询比当前版本更高且匹配硬件与产品的已发布应用。 - 3
用户确认安装
start_ota设备核对候选版本和 SHA-256，自行下载、校验、写入备用槽并重启。服务器没有强制安装接口。
- 4
重新连接并确认
get_ota_status小程序重连设备，核对目标版本与
boot_state=valid。下载成功、设备断线或服务器检查记录都不能单独证明安装成功。
这些命令描述客户端与固件需要遵循的流程；服务器接口可用不代表小程序、固件及真实硬件已经完成验收。旧分区设备需先按迁移流程完成有线迁移。
明确当前能力
接入前需要知道
后台目录与板端文件
角色目录可用于读取当前后台的角色、音色标识、提示词和表情信息。板端清单与文件下载用于同步当前资源配置允许的文件。
角色目录是现有管理／模拟器接口。小程序需要自行接入与映射，后台新增角色不会自动同步到小程序。
独立小程序业务层
目前没有独立的小程序用户登录、收藏接口、角色商店、同步任务状态 API，或按角色版本生成的资源包接口。
板端清单不承载角色名称、提示词、音色或 .role.json。默认资源配置也不下发 Live2D 文件。
处理错误时保留接口边界
401管理令牌、运维会话或设备签名失败。先确认当前请求使用哪一种凭据。
403当前身份或设备条件不允许操作；OTA 还需核对设备登记、硬件与迁移状态。
404 / 409资源不存在、文件不在清单、清单已变化或配置版本冲突。重新读取对应状态后处理。
429设备签名请求达到频率限制。采用退避重试，并为新请求生成新的 nonce 与签名。
交给开发与联调