调用UploadMediaByURL实现媒体文件的URL批量拉取上传-视频点播-阿里云

基于源文件URL，拉取音视频媒体文件进行上传，支持批量上传。

接口说明

请确保在使用该接口前，已充分了解视频点播产品的收费方式和价格。媒资文件上传到视频点播中会产生存储费用，计费详情，请参见媒资存储计费。如果您已开通了存储传输加速，则上传媒资文件到视频点播时还将涉及上传加速费用，计费详情请参见存储传输加速计费。
本接口支持上传的媒体文件格式，请参见媒体格式。
本接口主要适用于文件没有存储在本地服务器或终端，需要通过公网访问的 URL 地址上传的场景。
本接口为异步上传接口，非实时，不保证时效性，一般提交后会在数小时、甚至数天内完成迁移上传。如果对时效性要求较高，建议使用上传 SDK 上传。
如果配置了回调，则上传完成后会收到 URL 上传视频完成的事件通知，可以通过获取 URL 上传信息接口查询上传状态。
上传任务提交成功后，会在云端生成异步执行的任务，相应服务地域下所有用户提交的 URL 上传任务进行排队执行，完成时间受已有任务数量影响；上传完成后可根据事件通知（消息回调）返回的 URL 和视频 ID 等信息进行关联。
本接口目前仅支持华东 2（上海）、华北 2（北京）、华南 1（深圳）、新加坡、美国（硅谷）地域。
同一个媒体文件 URL，每次提交上传任务都会在点播中产生一个新的媒体资源（即产生新的媒体 ID）。
单个文件超过 20GB 时，将导致上传失败。如您有单个文件超过 20GB 的上传需求，请使用上传 SDK 进行上传。详细信息请参见上传 SDK 概述。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
vod:UploadMediaByURL	create	全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值
UploadURLs	string	是	媒体源文件 URL。 URL 中需要包括扩展名, 比如`https://**.mp4`中 mp4 为扩展名。如果 URL 中不包含扩展名，可以在`UploadMetadatas`中传入`FileExtension`来指定。如果 URL 中有扩展名且同时传入`FileExtension`，以传入的`FileExtension`为准。指定支持的扩展名，请参见上传概述。说明 URL 编码，多个地址之间以半角逗号（,）分隔，最多支持 20 个，避免存在特殊字符导致无法上传视频，需要 URL 编码后**再做逗号拼接。	https://****.mp4
TemplateGroupId	string	否	转码模板组 ID。可通过以下方式获取：登录点播控制台，选择配置管理 > 媒体处理配置 > 转码模板组查看转码模版组 ID。通过创建转码模板组接口创建转码模板组时，转码模板组 ID 为返回参数 TranscodeTemplateGroupId 的值。通过查询转码配置列表接口查询转码模板组时，为请求后返回参数 TranscodeTemplateGroupId 的值。说明不设置转码模板组 ID，则按默认的转码模板组进行转码；设置了转码模板组 ID 时，会使用该指定的模板组进行转码。可以在`UploadMetadatas`中进行设置，如果在 UploadMetadatas 中设置了 TemplateGroupId，此处也设置了 TemplateGroupId，则以 UploadMetadatas 中设置的 TemplateGroupId 为准。	ca3a8f6e4957b65806709586****
StorageLocation	string	否	媒体文件存储地址。登录点播控制台，选择配置管理 > 媒资管理配置 > 存储管理查看存储地址。不指定时会使用默认存储地址。	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
UploadMetadatas	string	否	上传媒体文件的元数据信息，为 JSON 字符串。与 UploadURLs 里的 URL 匹配才能生效。 JSON 格式：`[UploadMetadata, UploadMetadata,…]`，需转为 JSON 字符串。更多信息，请参见下表 UploadMetadata。	[{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
UserData	string	否	自定义设置。为 JSON 字符串，支持消息回调、上传加速等设置。更多信息，请参见 UserData 。说明此参数中消息回调的使用前提是需要在控制台配置 HTTP 回调地址和勾选对应的回调事件类型才能使用，否则回调设置不生效。控制台配置 HTTP 回调的操作，请参考回调设置。如需使用上传加速功能，您需要提交工单申请开通，更多信息，请参见上传相关说明。关于如何提交工单，请参见联系我们。	{"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
AppId	string	否	应用 ID。默认取值：app-1000000。更多信息，请参见多应用。	app-****
WorkflowId	string	否	工作流 ID。可登录点播控制台，选择配置管理 > 媒体处理配置 > 工作流管理查看工作流 ID。说明如果同时传递了 WorkflowId 和 TemplateGroupId，以 WorkflowId 为准。使用说明，请参见工作流。	e1e243b42548248197d6f74f9****
SessionId	string	否	自定义去重识别码，如果传递了该参数请求，当检测到在过去 10 分钟内曾有过相同识别码的请求，则会在本次请求时返回错误。说明该去重识别码由您自定义设置，长度最长为 50 个字符，支持大小写英文字母、数字、短划线（-）和下划线（_），不传或者带空字符串表示不去重。	5c62d40299034bbaa4c195da330****

UploadMetadata

名称	类型	是否必需	描述
SourceURL	String	是	需要上传的媒体源文件 URL。
Title	String	否	媒体标题。长度不超过 128 个字节。UTF-8 编码。
FileSize	String	否	文件大小。
Description	String	否	描述。长度不超过 1024 个字节。UTF-8 编码。
CoverURL	String	否	自定义视频封面 URL 地址。
CateId	String	否	分类 ID。可通过登录点播控制台，选择配置管理 > 媒资管理配置 > 分类管理查看分类 ID。
Tags	String	否	标签。单个标签不超过 32 字节，最多不超过 16 个标签。多个标签，请使用半角逗号（,）分隔。UTF8 编码。
TemplateGroupId	String	否	转码模板组 ID。会覆盖外层传入的 TemplateGroupId。
WorkflowId	String	否	工作流 ID。如果同时传入了 WorkflowId 和 TemplateGroupId，以 WorkflowId 为准。更多信息，请参见工作流。
FileExtension	String	否	媒体文件扩展名，支持的扩展名，请参见上传概述。

说明

UploadMetadata 中的参数（如 Title、Description、Tags 等）不能包含表情符。

为确保正常播放，当 TemplateGroupId 设置为“VOD_NO_TRANSCODE”不转码的方式上传视频文件后，目前仅以下格式的文件支持不转码直接播放：MP4、FLV、MP3、M3U8、WEBM，其他格式仅支持存储（关注 FileName 的扩展名）。若使用阿里云播放器，版本须为 3.1.0 或以上。

指定不转码的模板组（TemplateGroupId 设置为“VOD_NO_TRANSCODE”），视频上传后仅有视频上传完成的事件通知，没有单个清晰度转码完成的事件通知。

如果配置了回调，视频上传完成后，除了上传和转码通知，还有 URL 上传视频完成事件通知。

批量提交时，每一个 SourceURL 有独立的通知。

返回参数

名称	类型	描述	示例值
	object	返回结果。
RequestId	string	请求 ID。	25818875-5F78-4AF6-D7393642CA58****
UploadJobs	array<object>	上传任务列表。
UploadJob	object	上传任务详情。
SourceURL	string	上传任务对应的源文件 URL。	http://example****.mp4
JobId	string	上传任务 ID。	ad90a501b1b94fb72374ad005046****

示例

正常返回示例

JSON格式

{
  "RequestId": "25818875-5F78-4AF6-D7393642CA58****",
  "UploadJobs": [
    {
      "SourceURL": "http://example****.mp4",
      "JobId": "ad90a501b1b94fb72374ad005046****"
    }
  ]
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2025-01-08	OpenAPI 描述信息更新	查看变更详情
2023-05-16	OpenAPI 入参发生变更	查看变更详情

接口错误码

下表列举了本接口特有的错误码。

错误代码	错误信息	HTTP 状态码	说明
InvalidParameter.UploadURLs	The specified parameter UploadURLs is not valid.	400	参数 UploadURLs 无效。