获取录制文件（V2）

1. 接口说明

查询指定课堂的录制文件是否已经生成，并在文件全部可用时返回访问地址。

接口自动识别整课录制和仅高光录制，调用方不需要指定录制类型。查询操作不会创建、重新执行或修改录制任务。

项目	内容
接口版本	V2
请求方式	POST
请求路径	/fileExistsV2
Content-Type	application/json; charset=utf-8
字符编码	UTF-8

实际请求域名及网关鉴权方式以部署环境提供的信息为准。本接口请求体不额外接收签名字段。

2. 请求参数

参数	类型	必填	说明
siteId	String	是	站点 ID；仅支持字母、数字、下划线和短横线，最长 128 个字符
classId	String	是	课堂 ID；仅支持字母、数字、下划线和短横线，最长 128 个字符
classStartTime	String	否	兼容历史整课文件查询时使用，格式为 yyyyMMdd；V2 录制任务通常不需要传入

请求示例

POST /fileExistsV2 HTTP/1.1
Host: {API 服务域名}
Content-Type: application/json; charset=utf-8

{
  "siteId": "doctest",
  "classId": "487012832"
}

历史整课文件查询示例：

{
  "siteId": "doctest",
  "classId": "487012832",
  "classStartTime": "20260805"
}

3. 响应参数

参数	类型	必定返回	说明
code	Integer	是	业务状态码，详见“状态码”
message	String	是	状态说明
fileExists	Boolean	是	true 表示本次录制对应的全部文件均已生成
onlyHighlight	Integer	否	0 表示整课录制，1 表示仅高光录制
classUrl	String	否	整课录制文件地址；仅整课文件生成成功时返回
files	Array	是	录制文件列表；文件未全部生成时返回空数组

files 元素

参数	类型	必定返回	说明
type	String	是	文件类型：full 为整课，highlight 为高光片段
url	String	是	文件访问地址
highlightId	Integer	否	高光记录 ID；仅 type=highlight 时返回

4. 响应示例

4.1 整课录制文件已生成

HTTP 状态码：200

{
  "code": 0,
  "message": "文件已生成",
  "fileExists": true,
  "onlyHighlight": 0,
  "classUrl": "https://xdymp4.xuedianyun.com/oss/doctest/20260805/487012832.mp4",
  "files": [
    {
      "type": "full",
      "url": "https://xdymp4.xuedianyun.com/oss/doctest/20260805/487012832.mp4"
    }
  ]
}

4.2 高光录制文件已生成

高光任务可能返回多个文件。只有全部高光文件都可用时，fileExists 才会返回 true。

HTTP 状态码：200

{
  "code": 0,
  "message": "文件已生成",
  "fileExists": true,
  "onlyHighlight": 1,
  "files": [
    {
      "type": "highlight",
      "highlightId": 5,
      "url": "https://xdymp4.xuedianyun.com/oss/doctest/20260805/487012832_highlight_5.mp4"
    },
    {
      "type": "highlight",
      "highlightId": 6,
      "url": "https://xdymp4.xuedianyun.com/oss/doctest/20260805/487012832_highlight_6.mp4"
    }
  ]
}

4.3 文件尚未生成

HTTP 状态码：200

{
  "code": 1,
  "message": "文件未生成",
  "fileExists": false,
  "files": []
}

fileExists=false 表示当前没有可交付的完整录制结果，可能处于录制中、文件同步中或没有生成录制文件。调用方可在业务允许的时间范围内继续查询。

4.4 请求参数错误

HTTP 状态码：400

{
  "code": 3,
  "message": "classId 无效",
  "fileExists": false,
  "files": []
}

4.5 服务异常

HTTP 状态码：500

{
  "code": -1,
  "message": "服务器内部错误",
  "fileExists": false,
  "files": []
}

5. 状态码

HTTP 状态码	code	说明
200	0	录制文件已全部生成，可以使用 files 中的地址
200	1	当前没有可交付的完整录制结果
400	2	siteId 或兼容日期参数无效
400	3	classId 无效
500	-1	服务内部异常

业务处理应同时判断 HTTP 状态码、code 和 fileExists。文件可交付的唯一判定条件为：

HTTP 200 && code == 0 && fileExists == true

6. 调用建议

1. 本接口为幂等查询接口，可以重复调用。
2. 建议轮询间隔不低于 10 秒，避免高频查询。
3. fileExists=false 时不会返回部分文件地址。
4. 收到 HTTP 500 时，可采用逐步延长间隔的方式重试。
5. 调用方应设置业务侧最长等待时间，避免无限轮询。

7. 版本记录

版本	日期	说明
V2	2026-08-10	支持统一查询整课录制和仅高光录制结果