A. HTTP API 参考

JoyInside 全量服务端 HTTP 接口的字典式速查。按鉴权、设备管理、角色管理、用户绑定、聊天记录、在线设备、视觉上报、网易云音乐分组。各接口详细字段说明见正文对应章节。
特别说明：接口参数productId，新产品对接请直接使用产品productId，历史产品保持兼容。

A.1 通用信息

API 地址

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

参数	必选	类型	说明
Authorization	是	string	鉴权头，格式固定为 `Bearer ${accessToken}`，其中 `accessToken` 为通过 getToken 接口获取的访问令牌。Token 获取方式见 4.1 Token 鉴权。

鉴权方式

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

Authorization: Bearer ${accessToken}

公共请求参数

参数	说明	出现场景
`requestId`	请求追踪，建议 UUID	多数接口
`vendorId`	企业 id（测试环境固定 `200196`）	多数接口
`botId`	设备唯一标识	多数接口
`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）

请求参数：

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

请求示例

完整请求示例(点击展开)

shell

curl --location 'https://api.joyinside.com/auth/getToken' \
--header 'Content-Type: application/json' \
--data '{
    "botId": "xxxxx",
    "accessVersion": "V2",
    "accessTimestamp": "1234567890",
    "accessNonce": "a",
    "accessKeyId": "1",
    "accessSign": "2"
}'

注意：参数botId与vendorId同时存在时，优先使用botId生成授权令牌

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

响应示例

完整响应示例(点击展开)

json

{
  "accessToken": "ehuc2065edbru==",
  "expireIn": 7200,
  "refreshToken": "cjekcnlsjfekncejh==",
  "refreshExpireIn": 604800,
  "code": 0,
  "msg": ""
}

详见 4.1 Token 鉴权 — 签名算法

A.2.2 刷新 Token

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

请求参数：

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

请求示例

完整请求示例(点击展开)

shell

curl --location 'https://api.joyinside.com/auth/refreshToken' \
--header 'Content-Type: application/json' \
--data '{
  "botId": "xxxxx",
  "accessKeyId": "xxxx",
  "refreshToken": "adasdfjklji1752=="
}'

注意：参数botId与vendorId同时存在时，优先使用botId生成授权令牌

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

字段	类型	是否必选	说明
accessToken	String	必选	用户访问令牌
expireIn	Integer	必选	访问令牌过期时间（秒）,有效期8小时，失效后重新生成或使用refreshToken生成新accessToken
code	Integer	必选	状态码
msg	String	必选	状态对应信息

响应示例

完整响应示例(点击展开)

json

{
  "accessToken": "xyzt7895edbru==",
  "expireIn": 7200,
  "code": 0,
  "msg": ""
}

A.3 设备管理

A.3.1 设备注册

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

请求参数：

字段	类型	必填	说明
vendorId	String	是	厂商唯一标识
productId	String	是	产品唯一标识
type	String	是	`PHYSICAL_ROBOT`（生产）/ `APP_ROBOT`（测试）
name	String	是	设备名称
deviceId	String	是	设备唯一标识,厂商保证唯一,建议用设备 SN
deviceModel	String	否	设备型号
timbreId	String	否	音色 id
desc	String	否	描述
resourceAuthedList	List<String>	否	JoyInside支持播放自有以及三方的音乐、故事资源。通过该字段指定设备后续进行资源检索、播放及计费所使用的资源提供方。若不传该字段，则默认使用 JoyInside 自有资源。注意：如需使用该字段，请提前联系JoyInside产品运营完成相关配置。取值：`WANG_YI_CLOUD`：网易云音乐

请求示例：

完整 JSON 示例(点击展开)

plaintext

{
  "vendorId": "1",
  "productId": "产品ID",
  "type": "APP_ROBOT",
  "name": "测试",
  "deviceId": "1"
}

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

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

A.3.2 设备列表

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

请求参数：

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

请求示例：

完整 JSON 示例(点击展开)

plaintext

{
   "requestId": "xxx",
   "vendorId": "1",
   "pageSize": 20,
   "pageNum": 1
}

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

Class PageResult

字段	数据类型	备注
records	Array	当前页数据列表，元素为机器人基础信息BotBaseInfoDetailDTO（见下表）
total	Long	总数（默认最多统计 10000 条）
size	Long	每页显示条数（默认 10 条）
current	Long	当前页码
pages	Long	总页数
optimizeCountSql	Boolean	是否自动优化 COUNT SQL，默认 true
searchCount	Boolean	是否进行 count 查询（默认 true）
maxLimit	Long	单页分页条数限制，可为 null
countId	String	countId，可为 null

Class BotBaseInfoDetailDTO

字段	数据类型	备注
vendorId	Long	厂商 id
botId	String	设备唯一标识
productId	String	产品唯一标识
shortCode	String	bot 短码
name	String	名称
modelId	Long	型号 id
type	String	类型
typeDesc	String	类型描述
sn	String	编号
defaultTimbreId	String	默认音色 id
timbreId	String	音色 id
cloneTimbres	Array<String>	克隆音色列表
desc	String	描述信息
createTime	Date	创建时间
createPin	String	创建人 pin
modifyTime	Date	更新时间
modifyPin	String	更新人 pin

A.3.3 移除设备克隆音色

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

请求参数：

字段	类型	必填	说明
botId	String	是	设备唯一标识
timbreId	String	是	音色 id

请求示例：

完整 JSON 示例(点击展开)

plaintext

{
    "botId":"xxxxx",
    "timbreId":"TIMBRE_20250512_0001"
}

返回 data：Bool（true 成功 / false 失败）。

成功响应：

完整 JSON 示例(点击展开)

plaintext

{
    "traceId": "b1f2c3d4e5f6a7b8",
    "state": "SUCCESS",
    "code": "OK",
    "result": null,
    "data": true
}

失败响应：

完整 JSON 示例(点击展开)

plaintext

{
    "traceId": "b1f2c3d4e5f6a7b8",
    "state": "FAILURE",
    "code": "",
    "result": "TIMBRE_20250512_0001该音色正在使用，无法删除",
    "data": false
}

A.3.4 音色试听

项目	说明
URL	`/device/timbre/ttsPlayV2`
方式	POST

请求参数：

字段	类型	必填	说明
requestId	String	是	请求追踪
botId	String	是	设备唯一标识
timbreId	String	是	音色 ID，取自 A.3.2 设备列表返回值中的克隆音色列表（cloneTimbres）
aue	int	否	音频编码格式，默认 0。1：pcm；2：opus（每次返回 N 个 opus 包，每包前 2 字节为包大小，每包 60ms）；3：mp3

请求示例：

完整 JSON 示例(点击展开)

json

{
    "requestId": "7f1c0c2e-9a13-4f0d-9d62-1f2f3a4b5c6d",
    "timbreId": "TIMBRE_20250512_0001",
    "botId": "xxxxx",
    "aue": 3
    
}

返回 data：byte[] — 合成后的音频数据，JSON 下为 Base64 字符串；编码格式由 aue 决定。

成功响应：

完整 JSON 示例(点击展开)

json

{
    "traceId": "b1f2c3d4e5f6a7b8",
    "state": "SUCCESS",
    "code": "",
    "result": null,
    "data": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAA//..."
}

失败响应（业务失败）：

完整 JSON 示例(点击展开)

json

{
    "traceId": "b1f2c3d4e5f6a7b8",
    "state": "FAILURE",
    "code": "006009",
    "result": "音频生成异常",
    "data": null
}

失败响应（系统异常）：

完整 JSON 示例(点击展开)

json

{
    "traceId": "b1f2c3d4e5f6a7b8",
    "state": "ERROR",
    "code": "99999",
    "result": "系统繁忙，请稍后再试",
    "data": null
}

A.4 AI 角色管理

A.4.1 系统角色列表

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

请求参数：

完整 JSON 示例(点击展开)

plaintext

{
  "requestId": "xxx",
  "vendorId": "1",
  "productId": "产品ID"
}

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

返回 data：List<SystemRole>

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

A.4.2 自定义角色列表

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

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

完整 JSON 示例(点击展开)

plaintext

{
   "requestId": "xxx",
   "vendorId": "1",
   "userId": "12345"
}

返回 data：List<VendorRoleDto>。

VendorRoleDto 结构见 A.4.8的VendorRoleDto

A.4.3 自定义角色详情

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

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

完整 JSON 示例(点击展开)

plaintext

{
   "requestId": "xxx",
   "vendorId": "1",
   "roleId": "xxxxx-1"
}

返回 data：VendorRoleDto。

VendorRoleDto 结构见 A.4.8的VendorRoleDto

A.4.4 自定义角色创建

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

请求参数：

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

返回 data：Bool（true 成功 / false 失败）。

⚠ 用户在企业产品维度下最多创建 10 个自定义角色。

A.4.5 自定义角色编辑

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

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

返回 data：Bool（true 成功 / false 失败）。

A.4.6 自定义角色删除

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

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

完整 JSON 示例(点击展开)

plaintext

{
   "requestId": "xxx",
   "vendorId": "xxx",
   "roleId": "xxxxx-1"
}

返回 data：Bool（true 成功 / false 失败）。

A.4.7 为设备绑定角色 ⭐

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

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

请求参数：

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

返回 data：Bool（true 成功 / false 失败）。

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

A.4.8 查询设备绑定角色

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

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

返回 data：VendorRoleDto

Class 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

请求参数：

完整 JSON 示例(点击展开)

plaintext

{
    "botId":"xxxxx",
    "uid":"绑定用户id",
    "userNickname":"用户昵称",
    "equipmentName":"设备称呼"
}

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

返回 data：Bool（true 成功 / false 失败）。

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

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

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

完整 JSON 示例(点击展开)

plaintext

{
    "requestId": "123456789",
    "botId":"xxxxx",
    "uid":"绑定用户id"
}

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

Class NickNameResponse

字段	数据类型	描述
botId	String	设备 id
uid	String	用户 uid
userNickname	String	用户昵称
equipmentName	String	设备称呼

完整 JSON 示例(点击展开)

plaintext

{
    "state": "SUCCESS",
    "code": "ok",
    "result": null,
    "data": {
        "botId": "xxxxx",
        "uid": "86797745-12a9-4020-897b-aa55bb26c3bc",
        "userNickname": "小明",
        "equipmentName": "小joy"
    }
}

A.5 音色

A.5.1 查询企业音色列表

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

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

完整 JSON 示例(点击展开)

plaintext

{
   "requestId": "xxx",
   "vendorId": "1"
}

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

Class VendorTimbreDTO

字段	数据类型	描述
id	Long	数据 id（可忽略）
timbreId	String	音色 id，后续保存、查询以此为准
voiceName	String	音色名称

A.6 用户绑定

设备绑定 uid 后，该设备对话归属到该用户，产生长期记忆与聊天报告。

A.6.1 绑定用户

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

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

字段	数据类型	是否必填	备注
requestId	String	是	请求追踪
botId	String	是	设备 id
uid	String	是	用户 id，关联长期记忆与聊天报告

返回 data：Boolean（true 绑定成功 / false 绑定失败）。

⚠ uid 关联长期记忆与聊天报告，必须与设备绑定用户保持一致。uid 规则（≤128 字节、必须真实）详见 4.3 核心参数总表。

A.6.2 查询设备绑定 uid

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

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

返回 data：String（uid）。

A.6.3 解绑用户

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

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

字段	数据类型	是否必填	备注
requestId	String	是	请求追踪
botId	String	是	设备 id
uid	String	是	用户 id，关联长期记忆与聊天报告
deleteMemory	Boolean	否	解绑时是否删除记忆，true 删除记忆 false 仅解绑

返回 data：Boolean（true 解绑成功 / false 解绑失败）。

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

A.7 聊天记录与报告

端侧获取聊天记录与报告数据，需要设备绑定用户（uid）后才能获取绑定用户的聊天数据记录。

A.7.1 获取聊天报告

聊天报告生成周期采用 T+1 模式（即次日生成聊天报告），且需提前联系JoyInside 运营团队开启每日对话分析功能配置。每天9点之后，端侧如采用定时任务调用接口来获取报告。时间点：9点，端侧最好做成可动态配置的时间点。

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

请求参数：

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

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

Class ChatReportDTO

字段	数据类型	描述
reportCode	String	报告 code
botId	String	设备 id
date	String	生成时间
contents	List<Content>	内容（name + value）
tipName	String	提示名
tipValue	String	提示值
publishTime	Long	发布时间戳

Class Content

字段	数据类型	描述
name	String	内容名
value	String	内容值

A.7.2 查询聊天记录

查询设备/会话维度的对话记录，支持按设备维度查询近 90 天内的聊天记录。

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

请求参数：requestId / vendorId 必填；botId 与 sn 二者至少填一个；startTime 必填（不能早于 90 天前）、endTime 选填；filterEmptyUserInput / filterEmptyModelOutput 必填；searchAfter（翻页游标）/ pageSize（默认 20，最大 500）/ deviceModel / uid / roleCode / includeAudioUrl 选填。

完整 JSON 示例(点击展开)

plaintext

{
    "requestId":"123456789",
    "vendorId":"1",
    "botId":"xxxxx",
    "startTime":1781625600000,
    "endTime":1781762520000,
    "pageSize":50,
    "filterEmptyUserInput":true,
    "filterEmptyModelOutput":true,
    "uid": "58997745-12a9-4020-897b-aa55bb26c3bc",
    "roleCode": "角色编码",
    "includeAudioUrl": true
}

字段	类型	必填	说明
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
roleCode	String	否	角色编码
includeAudioUrl	Boolean	否	是否返回音频 URL，默认 false（不返回）；传 true 时响应携带 inputAudioUrl/outputAudioUrl

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

Class ChatMessagePageResult

字段	数据类型	描述
data	List<ChatMessageVO>	当前页数据
total	Long	总命中数（ES 默认最多统计 10000 条）
hasNext	Boolean	是否有下一页
nextCursor	String	下一页游标，翻页时回传

Class ChatMessageVO 字段：asrText / startTime / ttsText / ttsTime / botId / sn / productId / securityStatus / uid / roleCode / inputAudioUrl / outputAudioUrl / roundId。

字段	数据类型	描述
asrText	String	用户说的话（ASR 识别结果）
startTime	Long	对话开始时间（时间戳毫秒）
ttsText	String	设备回复的话（TTS 文本）
ttsTime	Long	TTS 请求时间（时间戳毫秒）
botId	String	设备 ID
sn	String	设备 SN
productId	String	产品唯一标识
securityStatus	Integer	安全审核状态（0 通过，1 不通过）
uid	String	用户 id
roleCode	String	角色编码
inputAudioUrl	String	用户语音输入音频 URL（includeAudioUrl=true 时返回，无音频时为 null）
outputAudioUrl	String	模型 TTS 输出音频 URL（includeAudioUrl=true 时返回，无音频时为 null）
roundId	String	轮次ID

完整 JSON 示例(点击展开)

plaintext

{
    "state": "SUCCESS",
    "code": "0000",
    "msg": null,
    "data": {
        "data": [
            {
                "asrText": "内蒙古九十九号公路",
                "startTime": 1781751367274,
                "ttsText": "哇，内蒙古的九十九号公路超级壮观，沿途都是草原美景！京东618，咱们可以自驾去，一路欣赏风景，怎么样？",
                "ttsTime": null,
                "botId": "xxxxx",
                "sn": "conversation-robot-2781690038317",
                "productId": "11966",
                "securityStatus": null,
                "uid": "54567745-12a9-4020-897b-aa55bb26c3bc",
                "roleCode": "角色编码",
                "inputAudioUrl": "https://.../xxx.pcm",
                "outputAudioUrl": "https://.../xxx.pcm",
                "roundId": "f1c5b622-2ffe-4fd2-b0be-3974cf887a61_1789660799918"
            },
            {
                "asrText": "有大草原吗？",
                "startTime": 1781751354883,
                "ttsText": "当然有啦！可以去张家口的坝上草原，那里风景超美，还能骑马呢！京东618，要不要去感受一下？",
                "ttsTime": null,
                "botId": "xxxxx",
                "sn": "conversation-robot-2781690038317",
                "productId": "11966",
                "securityStatus": null,
                "uid": "54567745-12a9-4020-897b-aa55bb26c3bc",
                "roleCode": "角色编码",
                "inputAudioUrl": "https://.../xxx.pcm",
                "outputAudioUrl": "https://.../xxx.pcm",
                "roundId": "f1c5b622-2ffe-4fd2-b0be-3974cf887a61_1789660799918"
            }
        ],
        "total": 2,
        "hasNext": false,
        "nextCursor": null
    }
}

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

A.8.1 查询用户在线设备

查询用户（uid）在某厂商（vendorId）下的所有在线设备列表。

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

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

字段	数据类型	是否必填	备注
vendorId	String	是	企业 id
uid	String	是	绑定用户 id

请求示例：

完整 JSON 示例(点击展开)

plaintext

{
  "vendorId": "1",
  "uid": "uid_test"
}

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

Class BotOnlineDTO

字段	数据类型	备注
botId	String	设备唯一标识
uid	String	关联用户 UID
vendorId	String	业务方厂商唯一标识
deviceId	String	设备 ID
sessionId	String	当前会话 ID
requestId	String	最近一次请求 ID（用于链路排查）
connectTime	Long	设备连接建立时间（毫秒）
updateTime	Long	数据最近更新时间（毫秒）
lastRoundStartTime	Long	最后一次会话开始时间（毫秒）
chatRoundCount	Integer	会话轮数
connectDuration	String	连接时长（可读字符串，如 "1h23m"）
silenceDuration	String	静默时长（可读字符串）

成功响应：

完整 JSON 示例(点击展开)

plaintext

{
  "state": "SUCCESS",
  "code": "0000",
  "msg": null,
  "data": [
    {
      "botId": "xxxxx",
      "uid": "xxxxx",
      "vendorId": null,
      "deviceId": "test-yy-langlangsha",
      "sessionId": "7d8fd31ddba44940b8ddb11f9e1485eb72864594-599f-4781-9537-dde54c7a794c",
      "requestId": "d6c079a7-9908-4517-ab74-134cc9aceb38",
      "connectTime": 1780072660495,
      "updateTime": 1780072675812,
      "lastRoundStartTime": 1780072675812,
      "chatRoundCount": 1,
      "connectDuration": null,
      "silenceDuration": null
    }
  ]
}

失败响应：

完整 JSON 示例(点击展开)

plaintext

{
  "state": "FAILURE",
  "code": "9999",
  "msg": null,
  "data": null
}

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

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

请求参数：

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

PlayStrategy 枚举：

策略	行为
`INTERRUPT`	强制打断当前 AI 回复后立即播放。全链路秒级，不阻塞 Provider 线程
`WAIT_IDLE`	同步等待进行中对话完成后插播，等待最大时间 `maxWaitMs`

⚠ WAIT_IDLE 策略同步阻塞整个等待窗口，调用方需保证 HTTP 超时充足。

请求示例：

完整 JSON 示例(点击展开)

plaintext

{
  "vendorId": "1",
  "botId": "xxxxx",
  "text": "您好，有什么可以帮您的？",
  "playStrategy": "INTERRUPT",
  "bizTag": "demo_scene",
  "bizRequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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

Class BroadcastInstantVO

字段	数据类型	备注
taskId	String	任务唯一标识，便于追踪/查询（成功时不为空）
pushed	Boolean	是否成功推送（true=已下发或已开始下发；false=被中止/未下发）
abortReason	String	未成功推送时的原因（成功时为 null）

成功响应：

完整 JSON 示例(点击展开)

plaintext

{
  "state": "SUCCESS",
  "code": "0000",
  "msg": null,
  "data": {
    "taskId": "021a41e5d42143a98eaa0b10f4b2d2bd",
    "pushed": true,
    "abortReason": null
  }
}

失败响应：

完整 JSON 示例(点击展开)

plaintext

{
  "state": "FAILURE",
  "code": "9999",
  "msg": null,
  "data": {
    "taskId": null,
    "pushed": false,
    "abortReason": "instant-wait-idle-timeout"
  }
}

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

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

请求参数：

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

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

请求/响应示例(点击展开)

请求示例:

json

{
  "requestId": "1",
  "botId": "xxxxx",
  "productId": "1",
  "sessionId": "12345678",
  "imgBase64": "imgBase64==",
  "frameTimestamp": 1761899917136
}

响应示例:

json

{
  "state": "SUCCESS",
  "code": "0000",
  "data": null
}

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

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

需要使用网易云音乐资源时，通过以下接口完成用户 OAuth 绑定与设备赋权。详见网易云账号绑定 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	§A.2.1
2	`/auth/refreshToken`	刷新 Token	§A.2.2
3	`/device/register`	设备注册	§A.3.1
4	`/device/list`	设备列表	§A.3.2
5	`/device/removeCloneTimbre`	移除设备克隆音色	§A.3.3
6	`/soulmate/timbre/ttsPlayV2`	音色试听	§A.3.4
7	`/agent/roles/query`	系统角色列表	§A.4.1
8	`/soulmate/role/customRole/list`	自定义角色列表	§A.4.2
9	`/soulmate/role/customRole/get`	自定义角色详情	§A.4.3
10	`/soulmate/role/customRole/save`	创建自定义角色	§A.4.4
11	`/soulmate/role/customRole/update`	编辑自定义角色	§A.4.5
12	`/soulmate/role/customRole/delete`	删除自定义角色	§A.4.6
13	`/soulmate/role/botBindRole/save`	设备绑定角色	§A.4.7
14	`/soulmate/role/botBindRole/get`	查询绑定角色	§A.4.8
15	`/soulmate/role/nickName/update`	修改用户昵称和设备称呼	§A.4.9
16	`/soulmate/role/nickName/get`	查询用户昵称和设备称呼	§A.4.10
17	`/soulmate/timbre/findAllByVendorId`	音色列表	§A.5.1
18	`/device/bindUser`	绑定用户	§A.6.1
19	`/device/queryBotBind`	查询绑定 uid	§A.6.2
20	`/device/unbindUser`	解绑用户	§A.6.3
21	`/soulmate/chatReport/recentDays`	聊天报告	§A.7.1
22	`/soulmate/chatReport/chatMessage/page`	聊天记录	§A.7.2
23	`/online/bot/query`	在线设备查询	§A.8.1
24	`/online/bot/broadcast/instant`	设备插播	§A.8.2
25	`/vision/client/image/report`	视觉图像上报	§A.9
26	`/soulmate/wyy/getWyyH5LoginConfig`	网易云登录配置	§A.10.1
27	`/soulmate/wyy/getWyyH5LoginResult`	网易云登录结果	§A.10.2
28	`/soulmate/wyy/getWyyAccountUser`	网易云账号信息	§A.10.3
29	`/soulmate/wyy/unbindWyyAccount`	解绑网易云账号	§A.10.4
30	`/soulmate/wyy/getWyyAccountBotList`	网易云已绑设备	§A.10.5
31	`/soulmate/wyy/bindBotWyyAccount`	网易云绑设备	§A.10.6
32	`/soulmate/wyy/unbindBotWyyAccount`	网易云解绑设备	§A.10.7

A. HTTP API 参考 ​

A.1 通用信息 ​

API 地址 ​

Header 参数说明 ​

鉴权方式 ​

公共请求参数 ​

统一返回结构 ​

A.2 鉴权接口 ​

A.2.1 获取 Token ​

A.2.2 刷新 Token ​

A.3 设备管理 ​

A.3.1 设备注册 ​

A.3.2 设备列表 ​

A.3.3 移除设备克隆音色 ​

A.3.4 音色试听 ​

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 地址

Header 参数说明

鉴权方式

公共请求参数

统一返回结构

A.2 鉴权接口

A.2.1 获取 Token

A.2.2 刷新 Token

A.3 设备管理

A.3.1 设备注册

A.3.2 设备列表

A.3.3 移除设备克隆音色

A.3.4 音色试听

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 接口一览表