前期准备
开始操作前，确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK，请先参考快速入门文档完成。
注意事项：
媒体与 HLS 相关接口需要 space_admin 或 admin 权限。
视频转码（createTranscodeTask）为异步任务，返回 taskId，需通过任务管理接口轮询执行结果。
m3u8 上传采用「准备 → 上传分片 → 确认 → （可选）续期/追加」的多步流程，请按本文档说明的顺序编排。
查询媒体文件元信息
功能说明
getMediaFileInfo 用于查询媒体文件的元信息，包括分辨率、码率、时长和可用的转码模板。使用示例
const res = await smh.hls.getMediaFileInfo({spaceId: 'your-space-id',filePath: '/videos/movie.mp4',info: 1,});if (res.status === 200) {console.log('分辨率:', res.data.width + 'x' + res.data.height);console.log('码率:', res.data.bitrate, 'kbps');console.log('时长:', res.data.duration, '秒');console.log('可用转码模板:', res.data.allowedTranscodingTemplates);}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
spaceId | 空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数 | String | 是 |
filePath | 媒体文件路径 | String | 是 |
info | 固定值 1，表示查询媒体文件元信息 | Number | 是 |
返回值说明
HTTP 状态码：200，查询成功。
字段 | 说明 | 类型 |
width | 视频宽度，单位 px，字符串格式 | String |
height | 视频高度，单位 px，字符串格式 | String |
bitrate | 码率，单位 kbps，字符串格式 | String |
duration | 时长，单位秒，字符串格式 | String |
allowedTranscodingTemplates | 允许使用的转码模板列表 | Array<String> |
视频转码
功能说明
createTranscodeTask 用于发起视频转码任务，将视频转码为指定分辨率的 HLS 格式。转码为异步任务，返回 taskId，需通过任务管理接口轮询执行结果。使用示例
const res = await smh.hls.createTranscodeTask({spaceId: 'your-space-id',filePath: '/videos/movie.mp4',transcode: 1,createTranscodeTaskRequest: {transcodingTemplateId: 'h264_720p',},});if (res.status === 200) {console.log('转码任务已提交，taskId:', res.data.taskId);// 通过任务管理接口轮询转码结果}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
spaceId | 空间 ID | String | 是 |
filePath | 源视频文件路径 | String | 是 |
transcode | 固定值 1，表示视频转码 | Number | 是 |
createTranscodeTaskRequest | 转码请求对象 | Object | 是 |
createTranscodeTaskRequest 对象说明
字段 | 参数描述 | 类型 | 是否必填 |
transcodingTemplateId | 转码模板：h264_360p（流畅）、h264_480p（低清）、h264_720p（高清）、h264_1080p（超清）、h264_2K、h264_4K；不允许大于原视频分辨率 | String | 是 |
返回值说明
HTTP 状态码：200，转码任务已提交。
字段 | 说明 | 类型 |
taskId | 异步转码任务 ID | Number |
实时转码（边转边播）
功能说明
liveTranscodeMediaFile 用于实时转码并获取播放列表，服务端通过 HTTP 302 重定向到真实的 m3u8 播放地址（axios 会自动跟随跳转，客户端实际观察到的 res.status 为最终响应的 200），可实现边转边播。仅支持将非 HLS 源文件转为 HLS 播放，不支持符号链接和历史版本。使用示例
const res = await smh.hls.liveTranscodeMediaFile({spaceId: 'your-space-id',filePath: '/videos/movie.mp4',liveTranscode: 1,transcodingTemplateId: 'h264_720p',});// 服务端返回 302，axios 自动跟随跳转后 res.status 为最终响应的 200console.log('Status:', res.status);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
spaceId | 空间 ID | String | 是 |
filePath | 源视频文件路径 | String | 是 |
liveTranscode | 固定值 1，表示实时转码 | Number | 是 |
transcodingTemplateId | 转码模板，同视频转码接口 | String | 是 |
下载转码后的视频
功能说明
downloadTranscodedVideo 用于下载转码后的视频。如果 m3u8 转封装未完成会返回 FileConverting 错误；如果转码任务未完成，会返回原始视频的下载链接。本接口在 file 模块中。使用示例
const res = await smh.file.downloadTranscodedVideo({spaceId: 'your-space-id',filePath: '/videos/movie.mp4',transcodingTemplateId: 'h264_720p',});// 服务端返回 302，axios 自动跟随跳转后 res.status 为最终响应的 200console.log('Status:', res.status);
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
spaceId | 空间 ID | String | 是 |
filePath | 视频文件路径 | String | 是 |
transcodingTemplateId | 转码模板：h264_360p、h264_480p、h264_720p、h264_1080p、h264_2K、h264_4K | String | 是 |
m3u8 上传
m3u8 上传用于将已切片好的 HLS 资源（m3u8 播放列表 + ts 分片）上传到 SMH，采用多步流程：
1. 上传准备（
prepareM3u8Upload）：提交播放列表与分片清单，获取 confirmKey 与各文件的预签名上传信息；命中秒传时直接完成。2. 上传分片：客户端按返回的预签名信息，将 playlist 和各 segment 直传 COS。
3. 上传完成（
confirmM3u8Upload）：分片上传完成后提交 CRC64 校验值确认，分批确认时最后确认 playlist。4. 上传续期（
renewM3u8Upload，可选）：预签名信息过期（expiration）前续期。5. 分片重传与追加（
modifyM3u8Segments）：分片失败重传或追加分片（分片数超过单次上限 100 个时分批追加，带密钥时上限 101 个）。上传准备
功能说明
prepareM3u8Upload（PUT + body），返回 201 表示需继续上传（含 confirmKey 和预签名信息），返回 200 表示秒传命中直接完成。使用示例
const res = await smh.hls.prepareM3u8Upload({spaceId: 'your-space-id',filePath: '/videos/hls/movie.m3u8',conflictResolutionStrategy: 'rename',prepareM3u8UploadRequest: {segments: [{ path: '1.ts' },{ path: '2.ts' },],},});if (res.status === 201) {console.log('ConfirmKey:', res.data.confirmKey);// 按 res.data.playlist 与 res.data.segments 中的预签名信息直传 COS} else if (res.status === 200) {console.log('秒传成功');}
prepareM3u8UploadRequest 对象说明
字段 | 参数描述 | 类型 | 是否必填 |
playlist | m3u8 播放列表内容（media playlist，固定简单上传） | Object | 否 |
segments | 分片清单，最多 100 个（带密钥 101 个），超出部分通过分片重传与追加接口分批上传 | Array | 否 |
sampleHash | 秒传抽样哈希，与 segmentsCount 捆绑使用 | String | 否 |
segmentsCount | 分片总数，字符串格式，与 sampleHash 捆绑使用 | String | 否 |
segments 元素说明：path（分片相对路径，如 1.ts 或 abc/def/1.ts）、uploadMethod（上传方式：simple 默认 / multipart）。
201 响应说明：confirmKey（上传确认标识）；playlist 与 segments（Map，key 为分片路径）中均含 domain、path、headers、expiration（过期时间，失效前需通过续期接口续期）；segments 的 uploadId 仅分块上传时返回。
上传完成
功能说明
confirmM3u8Upload（POST + confirm=1 + confirmKey），提交各分片与播放列表的 CRC64 校验值完成上传。分片较多时可分批确认（每批最多 100 个 ts，有密钥 101 个），最后一批或单独最后确认 playlist。使用示例
const res = await smh.hls.confirmM3u8Upload({spaceId: 'your-space-id',confirmKey: 'confirm-key-from-prepare',confirm: 1,confirmM3u8UploadRequest: {segments: [{ path: '1.ts', crc64: 'crc64-of-segment-1' },{ path: '2.ts', crc64: 'crc64-of-segment-2' },],// playlist 的 crc64 与最后一批 segments 同传，或单独最后提交},});if (res.status === 200) {console.log('播放列表路径:', res.data.playlist?.path);}
上传续期与分片重传追加
功能说明
renewM3u8Upload（POST + renew=1 + confirmKey）：续期 playlist 和/或指定分片的预签名上传信息，body 中 playlist（固定 'm3u8'）与 segments（路径数组，最多 100/101 个）按需传入。modifyM3u8Segments（POST + modify=1 + confirmKey）：重传失败分片或追加分片，body 的 segments 结构同上传准备接口。使用示例
const res = await smh.hls.renewM3u8Upload({spaceId: 'your-space-id',confirmKey: 'confirm-key-from-prepare',renew: 1,renewM3u8UploadRequest: {segments: ['1.ts', '2.ts'],},});if (res.status === 200) {// 使用新的预签名信息（含新的 expiration）继续上传console.log('续期完成:', Object.keys(res.data.segments || {}));}
