服务端 API 文档

媒体上传综述

最近更新时间:2020-06-28 17:07:16

媒体上传是指用户将视频、音频、封面图片等媒体文件上传到云点播的存储中,以进行后续的处理和分发等。

上传方式

云点播支持以下几种上传方式:

  • 控制台本地上传
    在云点播控制台上传页面进行操作,将本地媒体文件上传到云点播。适用于开发者直接管理少量媒体的场景,具有方便快捷、无技术门槛的优点。
  • 控制台拉取上传
    在云点播控制台上传页面进行操作,指定待上传媒体的 URL,由云点播后台进行离线拉取。
  • 服务端上传
    开发者将存储在其后台服务器中的媒体文件上传到云点播,适用于自动化、系统化的生产环境。云点播提供了以下编程语言的服务端上传 SDK:
  • 客户端上传
    终端用户将客户端本地视频上传到云点播,适用于 UGC、PGC 等场景。云点播提供了以下平台的客户端上传 SDK:
  • API 拉取上传
    使用云点播提供的服务端 API 拉取上传接口,指定待上传媒体的 URL,由云点播后台进行离线拉取。适用于大量或自动化的媒体文件迁移场景。
  • 直播录制
    通过云直播提供的录制功能,将直播流的视频内容存储到云点播,以进行存档、剪辑和回看等。

存储地域

已支持地域列表

云点播在全球多个地域有存储节点,媒体上传过程中会选择其中一个地域进行存储。云点播目前支持的存储地域如下:

存储地域 地域英文简称
北京 ap-beijing
上海 ap-shanghai
重庆 ap-chongqing
天津 ap-beijing-1

开通存储地域

多存储地域的一个重要作用是提升媒体上传质量(成功率和速度)。上传者与存储节点的距离对上传质量有影响,一般来说近距离的上传质量要优于远距离。

开发者开通云点播服务后,云点播会自动分配重庆存储地域。开发者可以根据业务需要开通其它的存储地域,具体操作请参见 上传存储设置存储地域一旦开通将无法关闭

默认存储地域

开发者已有的存储地域中,有且仅有一个将作为默认存储地域。如果开发者仅有1个存储地域(即重庆),那么它将是默认存储地域;如果开发者开通了多个存储地域,那么可以在控制台选择其它地域作为默认存储地域。具体操作请参见 存储地域设置

默认存储地域的作用:在某些场景下,优先选择该地域作为媒体上传的目标地域。具体说明请阅读下文。

选择存储地域

媒体上传时需要选择一个存储地域,默认由云点播后台自动选择,也可以由开发者在上传请求中指定。

  • 当云点播后台自动选择存储地域时:
    • 如果开发者仅有1个存储地域(即重庆),那么所有上传的媒体都会存储在该地域。
    • 如果开发者开通了多个存储地域,那么各种上传方式的选择策略如下:
      上传方式 地域选择策略
      控制台本地上传 根据上传者地理位置,就近选择存储地域
      控制台拉取上传 固定选择默认存储园区
      服务端上传 根据上传者地理位置,就近选择存储地域
      客户端上传 根据上传者地理位置,就近选择存储地域
      API 拉取上传 固定选择默认存储园区
      直播录制 根据直播推流所在地域,就近选择存储地域
  • 当开发者指定存储地域时,各种上传方式的指定方法如下:
    上传方式 地域指定方法
    控制台本地上传 不支持
    控制台拉取上传 不支持
    服务端上传
    客户端上传 客户端上传签名参数
    API 拉取上传 拉取上传接口 StorageRegion 参数
    直播录制 不支持

功能与限制

媒体类型

云点播支持上传以下类型的媒体文件:

  • 视频:MP4、TS、FLV、WMV、ASF、RM、RMVB、MPG、MPEG、3GP、MOV、WEBM、MKV、AVI
  • 音频:MP3、M4A、FLAC、OGG、WAV
  • 封面图片:JPG、JPEG、PNG、GIF、BMP、TIFF、AI、CDR、EPS

事件通知

媒体上传完成后,云点播后台可以将这一事件通知给开发者。事件通知原理请参见 事件通知,配置方法请参见 事件通知配置
各种上传方式对应的事件通知类型如下:

上传方式 事件通知类型
  • 控制台本地上传
  • 服务端上传
  • 客户端上传
  • 直播录制
视频上传完成
  • 控制台拉取上传
  • API 拉取上传
URL 拉取视频上传完成

附属功能

云点播媒体上传支持多种附属功能,包括媒资管理相关、视频处理和事件通知相关、上传控制相关。

媒资管理相关

  • 附带封面:在上传视频的同时附带上传一张图片,该图片将在云点播媒资系统中自动设为该视频的封面。
  • 指定过期时间:在上传时指定该媒体文件的过期时间,当到达指定时间后,云点播后台自动删除该媒体文件及其附属文件(如转码文件、截图等)。
  • 指定分类:在上传后将该媒体文件设置为某个分类。

各种上传方式的支持情况和用法如下表:

功能 控制台本地上传 控制台拉取上传 服务端上传 客户端上传 API 拉取上传 直播录制
附带封面 不支持 不支持 拉取上传接口 CoverUrl 参数 不支持
指定过期时间 不支持 不支持 不支持 拉取上传接口 ExpireTime 参数 录制配置
指定分类 指定分类 不支持 客户端上传签名 classId 参数 拉取上传接口 ClassId 参数 不支持

视频处理和事件通知相关

  • 自动视频处理:在上传媒体的同时指定一个 任务流,上传完成后,云点播自动执行该任务流。常见的场景有:截取视频首帧图像作为封面、转码和内容审核等。
  • 视频处理事件通知透传字段:如果启用了自动视频处理,在处理完成后,云点播后台发起事件通知时透传该字段给开发者。
  • 上传事件通知透传字段:在上传完成后,云点播后台发起事件通知时透传该字段给开发者。

各种上传方式的支持情况和用法如下表:

功能 控制台本地上传 控制台拉取上传 服务端上传 客户端上传 API 拉取上传 直播录制
自动视频处理 上传后自动进行视频处理 不支持 客户端上传签名 procedure 参数 拉取上传接口 Procedure 参数 不支持
视频处理事件通知透传字段 不支持 不支持 不支持 客户端上传签名 sessionContext 参数 拉取上传接口 SessionContext 参数 不支持
上传事件通知透传字段 不支持 不支持 客户端上传签名 sourceContext 参数 不支持 不支持

上传控制相关

  • 断点续传:上传过程如果意外终止(如网络中断、关闭浏览器等),当用户再次尝试上传同一文件时,可以从中断处继续上传,不需要重新上传整个文件。
  • 暂停/恢复上传:上传过程中,用户可以主动暂停,并可主动恢复上传。
  • 取消上传:上传过程中,用户可以主动终止本次上传。
  • 获取上传进度:媒体已上传到云点播部分的大小占比。
  • 分片上传:在上传时将媒体文件切分为多个小分片,分别上传。一方面可以在弱网环境下将网络异常导致的中断影响降低;另一方面可以在高带宽环境中并发上传多个分片,充分利用网络带宽。

各种上传方式的支持情况和用法如下表:

功能 控制台本地上传 控制台拉取上传 服务端上传 客户端上传 API 拉取上传 直播录制
断点续传 不支持 不涉及 不支持 不涉及 不涉及
暂停和恢复上传 不支持 不涉及 不支持 不涉及 不涉及
取消上传 刷新或关闭浏览器页面 不涉及 不支持 不涉及 终止录制任务
获取上传进度 页面默认显示进度 不支持 不支持 不支持 不涉及
分片上传 已启用 不涉及
  • Web SDK 默认启用
  • Android SDK 默认启用
  • iOS SDK 默认启用
  • 小程序 SDK 不支持
不涉及 不涉及

限制

  • 媒体文件大小的限制如下:
    上传方式 媒体大小限制
    • 控制台本地上传
    • 客户端上传 - Web SDK
    60GB
    • 服务端上传
    • 控制台拉取上传
    • API 拉取上传
    48.82TB(50,000GB)
    • 客户端上传 - Android SDK
    • 客户端上传 - iOS SDK
    10GB
    直播录制
    • MP4/FLV 格式为48.82TB(50,000GB)
    • HLS 格式总大小无限制
    • 其它限制取决于 直播录制
  • 文件数量:无限制。
目录