7.2 外部媒体资源接入

有声书 / 音乐等内容从哪来？JoyInside 三方资源 Skill 支持资源播放、续播、播放控制等逻辑。三方需实现标准 API 协议，完成资源检索与资源详情两个接口。
本文只讲「内容从哪来」——资源检索与详情接口；播放协议（开播 / 停播 / 串场词）见 6.2 媒体资源接入。

7.2.1 接入流程图

特别说明：外部媒体资源接入，需要先对接播放协议：见6.2 媒体资源接入。

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

7.2.2 鉴权方式

JoyInside 对接三方资源，统一使用 Header 中追加 Authorization 请求头方式鉴权。
三方需提供一个长期有效的访问令牌(access_token)、资源检索接口地址(search_url) 以及资源详情接口地址(detail_url)，由 JoyInside 运营团队维护配置：

访问令牌(access_token)：zzz
资源检索接口地址(search_url)：https://xxx
资源详情接口地址(detail_url)： https://yyy

7.2.3 资源检索接口

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

入参：

参数名	数据类型	备注
query	String	用户本轮输入
messages	List<Message>	历史对话（近期三轮记忆，支持多轮检索）
excludeResourceIdList	List<String>	待排除的 id 集合（按播放顺序填充，用于续播）
recallCount	Number	召回个数
requestId	String	请求 id
similar	Double	相似度阈值
appId	String	JoyInside 产品 id
deviceId	String	设备 SN 码
botId	String	JoyInside 设备 id
resourceName	String	资源名
resourceAuthor	String	资源作者
resourceTags	String	资源标签
intent	String	意图

请求入参示例

请求入参示例（点击展开）

json

{
  "query": "我想听周杰伦的七里香",
  "messages": [
        {
            "role": "user",
            "content": "用户第一轮输入"
        },
        {
            "role": "assistant",
            "content": "agent第一轮回复"
        },
        {
            "role": "user",
            "content": "用户第二轮输入"
        },
        {
            "role": "assistant",
            "content": "agent第二轮回复"
        }
   ],
  "excludeResourceIdList": ["1", "2"],
  "recallCount": 20, 
  "requestId": "xxx",
  "similar": 0.95,
  "appId": "JoyInside产品id",
  "deviceId": "设备SN码",
  "botId": "JoyInside设备id",
  "resourceName": "七里香",
  "resourceAuthor": "周杰伦",
  "resourceTags": [],
  "intent": "歌曲点播 | 有声书点播"
}

参数名	参数类型	备注
state	String	`SUCCESS` / `FAILURE` / `ERROR`
code	String	`0000` 成功，非 `0000` 错误码
result	String	接口调用信息
data	List<RecallDTO>	召回数据

RecallDTO：

参数名	参数类型	备注
resourceId	String	资源 id（有声书：章节 id；音乐：歌曲 id）
resourceName	String	资源名称
score	Double	检索分数

返回值示例

返回值示例（点击展开）

json

{
  "state": "SUCCESS",
  "code": "0000",
  "result": "成功",
  "data": [
    {
      "resourceId": "资源id1",
      "resourceName": "资源名1",
      "score": 1.0
    }, {
      "resourceId": "资源id2",
      "resourceName": "资源名2",
      "score": 0.97
    }
  ]
}

7.2.4 资源详情接口

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

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

请求入参示例

请求入参示例（点击展开）

json

{
  "resourceId": "resourceId1",
  "requestId": "xxx",
  "appId": "JoyInside产品id",
  "deviceId": "设备SN码",
  "botId": "JoyInside设备id"
}

参数名	参数类型	备注
state	String	`SUCCESS` / `FAILURE` / `ERROR`
code	String	`0000` 成功，非 `0000` 错误码
result	String	接口调用信息
data	ResourceDetailDto	资源详情

ResourceDetailDto：

参数名	参数类型	备注
resourceId	String	资源 id
resourceName	String	资源名称（章节名 / 歌曲名）
parentId	String	父 id（有声书：书 id；音乐：专辑 id）
url	String	资源地址
author	String	作者 / 歌手
fileType	String	文件类型（目前只支持 mp3）
duration	Double	总时长（秒）
banner	String	封面图地址
tags	List<String>	资源标签

返回值示例

返回值示例（点击展开）

json

{
  "state": "SUCCESS",
  "code": "0000",
  "result": "成功",
  "data": {
    "resourceId": "资源id1",
    "resourceName": "资源名称1",
    "parentId": "父id",
    "url": "http://xxx/xx.mp3",
    "author": "jay",
    "fileType": "mp3",
    "duration": 200.0,
    "banner": "http://xxx/xxx.img",
    "tags": [
      "儿歌",
      "90后"
    ]
  }
}

7.2.5 多轮检索与续播机制

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

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

下一步

播放协议：读 6.2 媒体资源接入 —— 开播 / 停播 / 心跳 / 播控事件全集
自定义技能与 A2A：读 7.1 外部智能体接入 —— 三方内容资源也可通过 A2A 流式输出

7.2 外部媒体资源接入 ​

7.2.1 接入流程图 ​

7.2.2 鉴权方式 ​

7.2.3 资源检索接口 ​

7.2.4 资源详情接口 ​

7.2.5 多轮检索与续播机制 ​

下一步 ​

7.2 外部媒体资源接入

7.2.1 接入流程图

7.2.2 鉴权方式

7.2.3 资源检索接口

7.2.4 资源详情接口

7.2.5 多轮检索与续播机制

下一步