全部产品
Search
文档中心

视频点播:客户端上传

更新时间:Jul 09, 2026

客户端上传是指将客户端媒体文件直接上传到点播存储。相对于服务端代理上传,客户端上传避免了业务服务器中转文件,节省了服务器资源。

客户端上传原理

核心概念

客户端(App/浏览器/小程序)先从 应用服务器(AppServer)获取一次性上传凭证,随后直接将文件上传至阿里云视频点播(基于OSS存储),全程无需经过服务器中转。

上传核心链路包含以下角色:

角色

说明

客户端

终端用户的 App 或浏览器,集成上传 SDK。

应用服务器(AppServer)

后端服务,负责调用VOD API获取凭证并下发。

视频点播服务

阿里云视频点播服务,签发上传凭证并创建媒资ID。

OSS存储

实际存储文件的对象存储,客户端直传目标。

说明

为什么需要应用服务器(AppServer):AccessKey不可存储在客户端。阿里云AccessKey(AK/SK)拥有账号级资源操控权限,内置于App或网页代码中易被非法获取引发云资源安全风险。

上传流程

客户端上传 SDK封装了OSS直传逻辑,文件无需服务端中转,因此需通过应用服务器(AppServer)获取授权。目前客户端上传SDK支持两种授权方式:上传地址和凭证方式STS Token方式

推荐使用上传地址和凭证方式,相比 STS Token,其授权更简单、安全性更高(支持单视频权限控制)、参数配置更灵活且冗余度更高。

上传地址和凭证方式

方式简介:客户端向服务端获取上传地址和凭证后直接上传媒体资源到OSS。

image

阶段一:获取上传地址和凭证

客户端向应用服务端(AppServer)发起HTTP请求,携带本次上传的业务参数(如 TitleFileNameCateIdTags 等媒资元数据)。AppServer收到后,使用持有的AK/SK调用VOD的CreateUploadVideo接口。VOD服务返回三个关键结果:

  • UploadAuth:临时上传令牌。

  • UploadAddress:目标OSS 路径(Base64 编码)。

  • VideoId:媒资唯一标识。

AppServer将这三者透传给客户端。

说明
  • 点播服务在下发上传地址和凭证时还会自动创建媒资信息(媒体 ID),用于媒资生命周期管理或媒体处理。请妥善保存媒体ID,作为媒资管理、音视频播放、媒体处理等的输入。

阶段二:直传文件

客户端拿到凭证后,调用上传 SDK 的初始化方法,传入UploadAuthUploadAddressVideoId和本地文件路径。SDK内部自动完成:

  1. 解析 UploadAddress,得到 OSS Endpoint 和 Object Key。

  2. 将文件按分片上传至 OSS 存储,过程支持断点续传和进度回调。

整个过程中,文件直接从客户端传到 OSS,不经过AppServer。

阶段三:返回上传结果

OSS 完成文件上传后,向客户端 SDK 返回成功状态,SDK 触发 onUploadSucceed 回调,携带 VideoId。与此同时,VOD 服务侧会自动感知上传完成,并根据预设的 TemplateGroupId 或 WorkflowId 触发转码和处理流水线。也可配置事件回调以主动接收FileUploadComplete事件通知。

说明

凭证过期处理UploadAuth有效期约 3000 秒。大文件上传期间若凭证过期,SDK 将触发onUploadTokenExpired回调。此时客户端需要重新请求AppServer调用刷新视频上传凭证获取新凭证后,客户端再调用resumeWithAuth(newAuth) 接口即可断点续传,无需重传已完成分片。

STS Token方式

方式简介:用户应用服务器向客户端下发STS Token,客户端向点播服务获取上传地址和凭证,再上传媒资到OSS。

image

阶段一:获取STS临时凭证

客户端向 AppServer 请求临时访问凭证。AppServer 使用 AK/SK 调用阿里云 STS 的AssumeRole接口,获取一组有时效限制的 AccessKeyIdAccessKeySecretSecurityToken(有效期可设 900~3600 秒),然后返回给客户端。完整 STS 授权流程请参见上传授权

阶段二:获取上传凭证 + 直传文件

客户端用STS Token 初始化上传 SDK。SDK 内部会自动携带 STS Token 调用 VOD 的 CreateUploadVideo(传入 TitleFileName 等参数),获取 UploadAuth + UploadAddress + VideoId,然后自动执行分片上传。整个过程对开发者透明,无需手动调用 VOD 接口。

阶段三:返回上传结果

上传地址和凭证方式相同。OSS 完成文件上传后,SDK 触发onUploadSucceed 回调,携带VideoId。VOD 服务侧自动触发转码和处理流水线。也可配置事件回调以接收FileUploadComplete事件通知。

方式对比

客户端上传支持两种授权方式,对应不同的流程:

对比项

上传地址和凭证方式(推荐)

STS Token 方式

凭证获取方

AppServer调用VOD接口直接获取。

AppServer调用STS 接口获取临时AK/SK/Token,客户端再向VOD获取

客户端职责

用凭证初始化 SDK,直接上传

用STS Token初始化 SDK,SDK自动向 VOD 换取凭证后上传

客户端与云端交互次数

1次(拿凭证后直传)

2次(先拿 Token,SDK 再拿凭证)

权限粒度

单个视频级别(每个 VideoId 独立凭证)

Bucket/Object 级别(Token 有效期内可操作多个文件)

适用场景

大多数场景,推荐使用

已有STS体系的存量项目

功能说明

分片上传

客户端上传 SDK 默认采用分片上传方式(默认分片大小1MB)。SDK 将待上传的文件分成多个碎片(Part)分别上传,上传完成之后将这些 Part 组合成一个完整的 Object。

分片上传的优势:

  • 提升大文件上传成功率:单个分片失败只需重传该分片,不需要从头开始。

  • 支持断点续传:上传失败后,可以从最后一个成功上传的分片继续。

  • 提升上传速度:多个分片可并发上传(Web可通过parallel参数设置,默认为5,移动端自动管理)。

  • 实时进度回调:分片粒度的上传进度回调,返回已上传字节数与文件总大小。

使用分片上传时,若上传失败可能会产生碎片文件,一般 7 天后会自动清除。还可以调用DeleteMultipartUpload接口手动清除碎片文件。

断点续传

如果上传过程中出现网络错误导致上传失败,客户端上传 SDK 支持从最后一个成功上传的分片开始继续上传,实现断点续传效果。

说明

SDK 自动处理断点续传。上传失败后重新上传时,会自动从最后一个成功上传的分片处继续,无需手动干预(图片体积较小,Android SDK对图片不启用断点续传机制)。

更多功能

功能点

说明

支持的媒体格式

支持的媒体格式请参见支持的媒体格式。支持本地文件上传和网络文件上传(URL 拉取方式)。

文件大小限制

本地文件:最大支持 48.8 TB 的单个文件。网络文件:最大支持 5 GB 的单个文件。设置 URL 上传时需要将 URL 编码后再传入使用,避免存在特殊字符导致无法上传。

媒资管理

支持设置元数据,如媒体标题(Title)、媒体标签(Tags)、媒体分类(CateId)、视频封面(CoverURL)等。可通过获取上传地址和凭证相关接口的参数设置。

音视频转码

支持通过指定转码模板组或工作流设置转码,也支持不转码。可通过获取上传地址和凭证相关接口的参数(如 TemplateGroupIdWorkflowId 等)设置。

上传控制

包括开始、停止、暂停、恢复。SDK 内部自动完成断点续传,无需手动处理。

上传加速

需联系商务申请开通上传加速功能。申请开通后,可通过 SDKUserData 参数中的 AccelerateConfig 参数设置。仅支持 SDK 上传方式,控制台上传不支持加速。

网络切换

支持移动网络 3G/4G 与 Wi-Fi 之间切换。为了避免浪费 3G/4G 网络下的流量,切换到 3G/4G 网络时,可以调用 pause 暂停上传;切换回 Wi-Fi 网络时,调用 resume 恢复上传(网络切换的判断逻辑需要应用自行实现)。

事件通知

支持设置回调获取上传事件通知。支持的事件请参见事件通知。配置回调请参见回调配置

支持的平台与版本

客户端上传 SDK 支持以下平台:

平台

语言

最低系统要求

相关文档

Web

JavaScript

支持PC 浏览器与移动端H5

使用JavaScript SDK上传文件

Android

Java/kotlin

Android 4.0 及以上

使用Android SDK上传文件

iOS

Objective-C

iOS 8.0 及以上

使用iOS SDK上传文件

微信小程序

JavaScript

基于微信小程序框架

使用微信小程序SDK上传文件

说明

各端 SDK 的详细版本变更记录请参见上传 SDK 发布历史

计费说明

媒资上传到视频点播不产生额外费用。相关费用来源于使用的阿里云视频点播服务资源。

计费项

说明

存储费用

上传完成后的媒体文件存储费用,按存储量和时长计费。

流量费用

上传流量免费(从客户端到视频点播的入方向流量不计费)。下行播放流量另计。

转码费用

如上传后触发转码,按输出文件时长和转码规格计费。不转码则不产生。

上传加速费用

开通并使用上传加速功能时,按加速流量额外计费。具体联系商务咨询。

说明

计费详情请参见基础服务计费资源包