A. HTTP API 参考

JoyInside 全量服务端 HTTP 接口的字典式速查。按鉴权、设备管理、角色管理、用户绑定、聊天记录、在线设备、视觉上报、网易云音乐分组。各接口详细字段说明见正文对应章节。

A.1 通用信息

API 地址

环境	域名
测试	`https://uat-api.joyinside.com`
生产	`https://api.joyinside.com`

鉴权方式

除 getToken / refreshToken 自身外，所有接口均需在 Header 中携带：

Authorization: Bearer ${accessToken}

Token 获取方式见 4.1 Token 鉴权。

公共请求参数

参数	说明	出现场景
`vendorId`	企业 id（测试环境固定 `200196`）	多数接口
`botId`	设备唯一标识	多数接口
`requestId`	请求追踪，建议 UUID	多数接口
`uid`	用户 id（≤128 字节），关联长期记忆与聊天报告	绑定 / 聊天接口

统一返回结构

字段	类型	说明
`state`	String	`SUCCESS` / `FAILURE` / `ERROR`
`code`	String	`0000` 或 `200` 成功；`50x` 系统错误
`msg` / `result`	String	错误描述（成功时为 null）
`data`	各接口不同	业务数据

部分早期接口 code 为数字 200，新接口统一为字符串 0000。

A.2 鉴权接口

A.2.1 获取 Token

项目	说明
URL	`/auth/getToken`
方式	POST
鉴权	无需 Token（本身用于获取 Token）

请求参数：

字段	类型	必填	说明
accessKeyId	String	是	AccessKey
accessTimestamp	String	是	13 位毫秒时间戳（≤5min 误差）
accessNonce	String	是	随机字符串（防重放）
accessVersion	String	是	固定 `V2`
accessSign	String	是	HMAC-MD5 签名
botId	String	否	设备标识，与 vendorId 二选一
vendorId	String	否	厂商标识，与 botId 二选一

字段	说明
accessToken	访问令牌（有效期 8h）
expireIn	访问令牌剩余有效秒数
refreshToken	刷新令牌（有效期 7d）
refreshExpireIn	刷新令牌剩余有效秒数

详见 4.1 Token 鉴权 — 签名算法

A.2.2 刷新 Token

项目	说明
URL	`/auth/refreshToken`
方式	POST
鉴权	无需 Token

请求参数：

字段	类型	必填	说明
accessKeyId	String	是	AccessKey
refreshToken	String	是	刷新令牌
botId	String	否	与 vendorId 二选一
vendorId	String	否	与 botId 二选一

返回：同 getToken（新的 accessToken + expireIn）。

A.3 设备管理

A.3.1 设备注册

项目	说明
URL	`/device/register`
方式	POST

请求参数：

字段	类型	必填	说明
vendorId	String	是	厂商唯一标识
appId	String	是	应用 ID（与 productId 二选一）
productId	String	是	产品 ID（与 appId 二选一）
type	String	是	`PHYSICAL_ROBOT`（生产）/ `APP_ROBOT`（测试）
name	String	是	设备名称
deviceId	String	是	设备唯一标识（厂商保证唯一）
deviceModel	String	否	设备型号
timbreId	String	否	音色 id
desc	String	否	描述
resourceAuthedList	List<String>	否	资源提供方（如 `WANG_YI_CLOUD`）

返回 data：String — 注册成功的 botId。

⚠ 同一 deviceId 重复注册返回已有 botId，不会生成新 botId。详见 4.2 设备注册

A.3.2 设备列表

项目	说明
URL	`/device/list`
方式	POST

请求参数：

字段	类型	必填	说明
requestId	String	是	请求追踪
vendorId	String	是	厂商 id
pageSize	Integer	是	每页条数（10~500）
pageNum	Integer	是	页码（≥1）
botId	String	否	筛选
appId	String	否	筛选
productId	String	否	筛选
sn	String	否	筛选
shortCode	String	否	bot 短码筛选

返回 data：PageResult<BotBaseInfoDetailDTO>（含 records / total / size / current / pages）。

A.4 AI 角色管理

A.4.1 系统角色列表

项目	说明
URL	`/agent/roles/query`
方式	POST
Content-Type	application/json

请求参数：

字段	类型	必填	说明
appId	String	是	应用唯一标识
requestId	String	是	每次请求唯一标识，建议 UUID
botId	String	否	设备唯一标识，与 vendorId 二选一
vendorId	String	否	厂商唯一标识，与 botId 二选一

返回 data：List<SystemRole>

字段	类型	说明
roleName	String	系统角色名称
roleCode	String	系统角色 code（等同 roleId，调用设备绑定角色接口时将该值传入 roleId）

A.4.2 自定义角色列表

项目	说明
URL	`/soulmate/role/customRole/list`
方式	POST

请求参数：requestId / vendorId / userId（均必填）。

返回 data：List<VendorRoleDto>。

A.4.3 自定义角色详情

项目	说明
URL	`/soulmate/role/customRole/get`
方式	POST

请求参数：roleId / vendorId / requestId（均必填）。

返回 data：VendorRoleDto。

A.4.4 自定义角色创建

项目	说明
URL	`/soulmate/role/customRole/save`
方式	POST

请求参数：

字段	类型	必填	说明
vendorId	String	是	企业 id
userId	String	是	用户 id（空代表系统预制伙伴）
requestId	String	是	请求追踪
roleName	String	是	角色名
roleCode	String	是	系统角色编码，通过 §G.4.1 查询列表选取。设备绑定角色成功后，会以该自定义角色中 roleCode 对应的系统角色更新对话运行时上下文
timbreId	String	否	音色 id，不为空时角色被绑定后将以自定义音色为准（自定义角色 timbreId 优先于系统角色默认 timbreId）

返回 data：Bool。

⚠ 每用户每企业最多 10 个自定义角色。

A.4.5 自定义角色编辑

项目	说明
URL	`/soulmate/role/customRole/update`
方式	POST

请求参数：vendorId / roleId / requestId 必填；roleName / roleCode / timbreId 选填。

返回 data：Bool。

A.4.6 自定义角色删除

项目	说明
URL	`/soulmate/role/customRole/delete`
方式	POST

请求参数：vendorId / roleId / requestId（均必填）。

返回 data：Bool。

A.4.7 为设备绑定角色 ⭐

角色不通过 WS 建连参数传入，改用此 HTTP 绑定接口（推荐方式）。

项目	说明
URL	`/soulmate/role/botBindRole/save`
方式	POST

请求参数：

字段	类型	必填	说明
vendorId	String	是	企业 id
roleId	String	是	角色编码。取值：1）系统角色 code（从 §G.4.1 列表选定）；2）自定义角色 ID（从 §G.4.2 列表选定）
botId	String	是	设备 id
requestId	String	是	请求追踪
roleType	String	否	`SYSTEM` 系统角色 / `CUSTOM` 自定义角色（不传默认 CUSTOM）

返回 data：Bool。

⚠ 旧方式 roleCode 建连参数不再推荐，新接入统一用绑定接口。 ⚠ 切换角色需重建 WebSocket 连接才能生效。

A.4.8 查询设备绑定角色

项目	说明
URL	`/soulmate/role/botBindRole/get`
方式	POST

请求参数：vendorId / botId / requestId（均必填）。

返回 data：VendorRoleDto

字段	类型	说明
id	Long	数据 id（可忽略）
vendorId	String	企业 id
userId	String	用户 id
roleId	String	角色（AI 伙伴）id
roleName	String	角色名
roleCode	String	系统角色编码
prologue	String	开场白
timbreId	String	语音音色 id
lang	String	语言偏好
enableInternetSearch	String	是否开启联网搜索
enableLongTermMemory	String	是否开启长期记忆
yn	Integer	删除标识
createTime	Date	创建时间
modifyTime	Date	更新时间
roleType	String	角色类型（SYSTEM / CUSTOM）

A.4.9 修改昵称和设备称呼

⚠ 特殊要求：需在 JoyInside 运营平台做相应配置，全局人设（agentProfile）必须使用 FreeMarker 模板语法引用昵称变量占位。平台配置若不含 ${agentName!"默认名称"} 占位符，通过接口修改昵称对该 App 完全无效，大模型始终用系统内置硬编码名称。

项目	说明
URL	`/soulmate/role/nickName/update`
方式	POST

请求参数：

字段	类型	必填	说明
botId	String	是	设备 id
uid	String	是	绑定用户 id
userNickname	String	否	用户昵称
equipmentName	String	否	设备称呼

返回 data：Bool。

A.4.10 查询昵称和设备称呼

项目	说明
URL	`/soulmate/role/nickName/get`
方式	POST

请求参数：botId（必填）/ uid（选填）/ requestId（选填）。

返回 data：NickNameResponse（botId / uid / userNickname / equipmentName）。

A.5 音色

A.5.1 查询企业音色列表

项目	说明
URL	`/soulmate/timbre/findAllByVendorId`
方式	POST

请求参数：vendorId / requestId（均必填）。

返回 data：List<VendorTimbreDTO>（timbreId / voiceName）。

A.6 用户绑定

A.6.1 绑定用户

项目	说明
URL	`/device/bindUser`
方式	POST

请求参数：uid / botId / requestId（均必填）。

返回 data：String（uid）。

⚠ uid ≤128 字节，必须真实。详见 4.3 核心参数总表。

A.6.2 查询设备绑定 uid

项目	说明
URL	`/device/queryBotBind`
方式	POST

请求参数：botId / requestId（均必填）。

返回 data：String（uid）。

A.6.3 解绑用户

项目	说明
URL	`/device/unbindUser`
方式	POST

请求参数：uid / botId / requestId（均必填）。

返回 data：Bool。

⚠ 解绑影响设备长期记忆与聊天报告。

A.7 聊天记录与报告

A.7.1 获取聊天报告

项目	说明
URL	`/soulmate/chatReport/recentDays`
方式	POST

请求参数：

字段	类型	必填	说明
recentDays	Number	是	查询天数
botId	String	是	设备 id
uid	String	是	用户 id（须与绑定用户一致）
requestId	String	是	请求追踪

返回 data：List<ChatReportDTO>（reportCode / date / contents / tipName / tipValue / publishTime）。

A.7.2 查询聊天记录

项目	说明
URL	`/soulmate/chatReport/chatMessage/page`
方式	POST

请求参数：

字段	类型	必填	说明
requestId	String	是	请求追踪
vendorId	Long	是	企业 id
botId	String	否	设备 id（与 sn 至少填一）
sn	String	否	设备 SN（与 botId 至少填一）
startTime	Long	是	开始时间戳（ms），不能早于 90 天前
endTime	Long	否	结束时间戳（默认当前）
filterEmptyUserInput	Boolean	是	过滤空用户输入
filterEmptyModelOutput	Boolean	是	过滤空模型输出
searchAfter	List	否	翻页游标（首次不传）
pageSize	Integer	否	每页大小（默认 20，最大 500）
deviceModel	String	否	设备型号
uid	String	否	用户 id

返回 data：ChatMessagePageResult（data / total / hasNext / nextCursor）。

ChatMessageVO 字段：asrText / startTime / ttsText / ttsTime / botId / sn / appId / securityStatus / uid / roleCode。

A.8 在线设备管理与插播

A.8.1 查询用户在线设备

项目	说明
URL	`/online/bot/query`
方式	POST

请求参数：vendorId / uid（均必填）。

返回 data：List<BotOnlineDTO>（botId / uid / deviceId / appId / appName / sessionId / requestId / connectTime / updateTime / lastRoundStartTime / chatRoundCount / connectDuration / silenceDuration）。

A.8.2 给在线设备插播一句话 ⭐

项目	说明
URL	`/online/bot/broadcast/instant`
方式	POST

请求参数：

字段	类型	必填	说明
vendorId	String	是	厂商标识
botId	String	是	设备标识
text	String	是	待播放文本（≤500 字符）
playStrategy	String	是	`INTERRUPT`（强制打断）/ `WAIT_IDLE`（等空闲）
maxWaitMs	Long	否	WAIT_IDLE 等待上限（默认 10000，硬上限 60000）
bizTag	String	否	业务标识（监控分桶）
bizRequestId	String	否	幂等 ID（建议 UUID）

返回 data：BroadcastInstantVO（taskId / pushed / abortReason）。

⚠ WAIT_IDLE 策略同步阻塞，调用方需保证 HTTP 超时充足。

A.9 视觉对话 — 图像上报

项目	说明
URL	`/vision/client/image/report`
方式	POST
鉴权	`Authorization: Bearer ${accessToken}`

请求参数：

字段	类型	必填	说明
requestId	String	是	请求追踪
botId	String	是	设备标识
appId	String	是	应用 ID
sessionId	String	是	当前 WebSocket 会话 ID（必须一致）
imgBase64	String	是	图像 Base64（JPEG）
frameTimestamp	Long	是	采集时间戳（ms）

返回：state + code（0000 成功）。

⚠ sessionId 必须与 WebSocket 建连时一致，否则图像无法关联到对话上下文。详见 6.6 视觉对话

A.10 网易云音乐账号绑定

需要使用网易云音乐资源时，通过以下接口完成用户 OAuth 绑定与设备赋权。详见 7.3.1 网易云账号绑定 API

A.10.1 获取 H5 登录配置

项目	说明
URL	`/soulmate/wyy/getWyyH5LoginConfig`
方式	POST

请求参数：requestId / vendorId / uid / h5Token（均必填）。

返回 data：WyyH5LoginConfigDto（clientId / state / clientType / redirectUrl）。

A.10.2 获取 H5 登录结果（轮询）

项目	说明
URL	`/soulmate/wyy/getWyyH5LoginResult`
方式	POST

请求参数：requestId / vendorId / state（均必填）。

返回 data：Boolean（是否已完成绑定）。

A.10.3 获取账号用户信息

项目	说明
URL	`/soulmate/wyy/getWyyAccountUser`
方式	POST

请求参数：requestId / vendorId / uid（均必填）。

返回 data：WyyAccountUserDto（nickname / avatarUrl / gender / vipDetail 等）。

A.10.4 解绑网易云账号

项目	说明
URL	`/soulmate/wyy/unbindWyyAccount`
方式	POST

请求参数：requestId / vendorId / uid（均必填）。

返回 data：Boolean。

A.10.5 获取已绑定设备列表

项目	说明
URL	`/soulmate/wyy/getWyyAccountBotList`
方式	POST

请求参数：requestId / vendorId / uid（均必填）。

返回 data：List<ResourceAccountBotDto>（botId / accountId / bindId 等）。

A.10.6 绑定设备

项目	说明
URL	`/soulmate/wyy/bindBotWyyAccount`
方式	POST

请求参数：requestId / vendorId / uid / botIdList（均必填）。

返回 data：Boolean。

A.10.7 解绑设备

项目	说明
URL	`/soulmate/wyy/unbindBotWyyAccount`
方式	POST

请求参数：requestId / vendorId / uid / botIdList（均必填）。

返回 data：Boolean。

网易云专用错误码：

code	说明
ok	成功
500	参数 / 服务端逻辑异常
1001	未绑定网易云账号
1002	绑定的网易云账号已过期

A.11 接口一览表

#	接口	用途	详见
1	`/auth/getToken`	签名换 Token	§G.2.1
2	`/auth/refreshToken`	刷新 Token	§G.2.2
3	`/device/register`	设备注册	§G.3.1
4	`/device/list`	设备列表	§G.3.2
5	`/agent/roles/query`	系统角色列表	§G.4.1
6	`/soulmate/role/customRole/list`	自定义角色列表	§G.4.2
7	`/soulmate/role/customRole/get`	自定义角色详情	§G.4.3
8	`/soulmate/role/customRole/save`	创建自定义角色	§G.4.4
9	`/soulmate/role/customRole/update`	编辑自定义角色	§G.4.5
10	`/soulmate/role/customRole/delete`	删除自定义角色	§G.4.6
11	`/soulmate/role/botBindRole/save`	设备绑定角色	§G.4.7
12	`/soulmate/role/botBindRole/get`	查询绑定角色	§G.4.8
13	`/soulmate/role/nickName/update`	修改昵称	§G.4.9
14	`/soulmate/role/nickName/get`	查询昵称	§G.4.10
15	`/soulmate/timbre/findAllByVendorId`	音色列表	§G.5.1
16	`/device/bindUser`	绑定用户	§G.6.1
17	`/device/queryBotBind`	查询绑定 uid	§G.6.2
18	`/device/unbindUser`	解绑用户	§G.6.3
19	`/soulmate/chatReport/recentDays`	聊天报告	§G.7.1
20	`/soulmate/chatReport/chatMessage/page`	聊天记录	§G.7.2
21	`/online/bot/query`	在线设备查询	§G.8.1
22	`/online/bot/broadcast/instant`	设备插播	§G.8.2
23	`/vision/client/image/report`	视觉图像上报	§G.9
24	`/soulmate/wyy/getWyyH5LoginConfig`	网易云登录配置	§G.10.1
25	`/soulmate/wyy/getWyyH5LoginResult`	网易云登录结果	§G.10.2
26	`/soulmate/wyy/getWyyAccountUser`	网易云账号信息	§G.10.3
27	`/soulmate/wyy/unbindWyyAccount`	解绑网易云账号	§G.10.4
28	`/soulmate/wyy/getWyyAccountBotList`	网易云已绑设备	§G.10.5
29	`/soulmate/wyy/bindBotWyyAccount`	网易云绑设备	§G.10.6
30	`/soulmate/wyy/unbindBotWyyAccount`	网易云解绑设备	§G.10.7

A. HTTP API 参考 ​

A.1 通用信息 ​

API 地址 ​

鉴权方式 ​

公共请求参数 ​

统一返回结构 ​

A.2 鉴权接口 ​

A.2.1 获取 Token ​

A.2.2 刷新 Token ​

A.3 设备管理 ​

A.3.1 设备注册 ​

A.3.2 设备列表 ​

A.4 AI 角色管理 ​

A.4.1 系统角色列表 ​

A.4.2 自定义角色列表 ​

A.4.3 自定义角色详情 ​

A.4.4 自定义角色创建 ​

A.4.5 自定义角色编辑 ​

A.4.6 自定义角色删除 ​

A.4.7 为设备绑定角色 ⭐ ​

A.4.8 查询设备绑定角色 ​

A.4.9 修改昵称和设备称呼 ​

A.4.10 查询昵称和设备称呼 ​

A.5 音色 ​

A.5.1 查询企业音色列表 ​

A.6 用户绑定 ​

A.6.1 绑定用户 ​

A.6.2 查询设备绑定 uid ​

A.6.3 解绑用户 ​

A.7 聊天记录与报告 ​

A.7.1 获取聊天报告 ​

A.7.2 查询聊天记录 ​

A.8 在线设备管理与插播 ​

A.8.1 查询用户在线设备 ​

A.8.2 给在线设备插播一句话 ⭐ ​

A.9 视觉对话 — 图像上报 ​

A.10 网易云音乐账号绑定 ​

A.10.1 获取 H5 登录配置 ​

A.10.2 获取 H5 登录结果（轮询） ​

A.10.3 获取账号用户信息 ​

A.10.4 解绑网易云账号 ​

A.10.5 获取已绑定设备列表 ​

A.10.6 绑定设备 ​

A.10.7 解绑设备 ​

A.11 接口一览表 ​

A. HTTP API 参考

A.1 通用信息

API 地址

鉴权方式

公共请求参数

统一返回结构

A.2 鉴权接口

A.2.1 获取 Token

A.2.2 刷新 Token

A.3 设备管理

A.3.1 设备注册

A.3.2 设备列表

A.4 AI 角色管理

A.4.1 系统角色列表

A.4.2 自定义角色列表

A.4.3 自定义角色详情

A.4.4 自定义角色创建

A.4.5 自定义角色编辑

A.4.6 自定义角色删除

A.4.7 为设备绑定角色 ⭐

A.4.8 查询设备绑定角色

A.4.9 修改昵称和设备称呼

A.4.10 查询昵称和设备称呼

A.5 音色

A.5.1 查询企业音色列表

A.6 用户绑定

A.6.1 绑定用户

A.6.2 查询设备绑定 uid

A.6.3 解绑用户

A.7 聊天记录与报告

A.7.1 获取聊天报告

A.7.2 查询聊天记录

A.8 在线设备管理与插播

A.8.1 查询用户在线设备

A.8.2 给在线设备插播一句话 ⭐

A.9 视觉对话 — 图像上报

A.10 网易云音乐账号绑定

A.10.1 获取 H5 登录配置

A.10.2 获取 H5 登录结果（轮询）

A.10.3 获取账号用户信息

A.10.4 解绑网易云账号

A.10.5 获取已绑定设备列表

A.10.6 绑定设备

A.10.7 解绑设备

A.11 接口一览表