JoyInside 接入手册

主题

7.2 外部媒体资源接入 ​

有声书 / 音乐等内容从哪来？JoyInside 三方资源 Skill 支持资源播放、续播、播放控制等逻辑。三方需实现标准 API 协议，完成资源检索与资源详情两个接口。

本文只讲「内容从哪来」——资源检索与详情接口；播放协议（开播 / 停播 / 串场词）见 6.2 媒体资源接入。

7.2.1 接入流程图 ​

以下时序图展示了用户点播场景下，资源检索接口与资源详情接口在播控链路中的调用顺序：

7.2.2 鉴权方式 ​

JoyInside 对接三方资源，统一使用 Header 中追加 Authorization 请求头方式鉴权。三方需提供一个长期有效的 access-token，由 JoyInside 维护。

7.2.3 资源检索接口 ​

项目说明
请求方式POST
鉴权方式Header（Authorization）

入参：

参数名数据类型备注
queryString用户本轮输入
messagesList<Message>历史对话（近期三轮记忆，支持多轮检索）
excludeResourceIdListList<String>待排除的 id 集合（按播放顺序填充，用于续播）
recallCountNumber召回个数
requestIdString请求 id
similarDouble相似度阈值
appIdStringJoyInside 应用 id
deviceIdString设备 SN 码
botIdStringJoyInside 设备 id
resourceNameString资源名
resourceAuthorString资源作者
resourceTagsString资源标签
intentString意图

返回：

参数名参数类型备注
stateStringSUCCESS / FAILURE / ERROR
codeString0000 成功，非 0000 错误码
resultString接口调用信息
dataList<RecallDTO>召回数据

RecallDTO：

参数名参数类型备注
resourceIdString资源 id（有声书：章节 id；音乐：歌曲 id）
resourceNameString资源名称
scoreDouble检索分数

7.2.4 资源详情接口 ​

项目说明
请求方式POST
鉴权方式Header（Authorization）

入参：resourceId / requestId / appId / deviceId / botId

返回 ResourceDetailDto：

参数名参数类型备注
resourceIdString资源 id
resourceNameString资源名称（章节名 / 歌曲名）
parentIdString父 id（有声书：书 id；音乐：专辑 id）
urlString资源地址
authorString作者 / 歌手
fileTypeString文件类型（目前只支持 mp3）
durationDouble总时长（秒）
bannerString封面图地址
tagsList<String>资源标签

7.2.5 多轮检索与续播机制 ​

  • 近期三轮记忆 + query：JoyInside 会把用户本轮 query 及前三轮对话作为参数给出，应对多轮播控场景
  • 排除已播放 id 续播：一个 session 下播放列表为空时，JoyInside 会重复调用检索接口完成续播，需排除已播放过的资源（excludeResourceIdList）
  • 父 id 概念：
    • 有声书专辑：取 excludeResourceIdList 最后一位查出所属书，返回对应 index 之后的章节
    • 音乐专辑：同上，返回对应 index 之后的歌曲
    • 若排除集合为空，按 query 和历史对话检索

资源检索到的内容，通过 6.2 媒体资源接入 的播放协议下发到设备。资源接口提供「内容」，播放协议处理「怎么播」。

下一步 ​