You need to enable JavaScript to run this app.
导航
视频点播
  • 文档首页
    • /视频点播/API 参考/媒资上传/URL 批量拉取上传
URL 批量拉取上传
最近更新时间：2024.09.23 16:38:16首次发布时间：2021.02.23 10:42:38
我的收藏

此接口支持通过源文件 URL 批量拉取媒体文件并上传至视频点播。

使用说明

  • URL 支持 HTTP 和 HTTPS。
  • 提交请求后，会生成异步执行的任务，排队执行。
  • 提交任务后，可通过以下方式获取任务信息：

注意事项

URL 必须是源文件 URL，不能是包含视频文件的页面 URL。

请求说明

请求地址：https://vod.volcengineapi.com?Action=UploadMediaByUrl&Version=2020-08-01

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

参数
类型
是否必选
示例值
描述
Action
String
是
UploadMediaByUrl
接口名称。当前 API 的名称为 UploadMediaByUrl。
Version
String
是
2020-08-01
接口版本。当前 API 的版本为 2020-08-01。
SpaceName
String
是
test

点播空间名称。可通过以下方式获取空间名称：

  • 在视频点播控制台空间管理页面查看当前账号下所有空间的名称。
  • 调用 ListSpace 接口获取当前账号下所有空间的名称。
URLSets
Object[]
是
-
URL 及其对应配置，限制 20 条。为 URLSet 数组的 JSON 字符串。
Md5
String
否
b9fd116504b***88e59a824878f07a
文件的 MD5 值。此参数不为空时，视频点播服务端会计算文件的 Md5 值，与您传入的 Md5 值进行对比，不一致会报错。
Tags
String
否
tag1
文件标签。多个以 , 分隔，不超过 36 个字符。
Title
String
否
demo
文件标题。不超过 128 个字符。
Category
String
否
image

素材类型。视频点播支持以下素材类型：

  • video: 视频。
  • audio: 音频。
  • image: 图片。
  • dynamic_img: 动图。
  • subtitle: 字幕。
  • font: 字体。
FileName
String
否
example.mp4

文件路径，即文件在点播存储中的存储位置。在视频点播中，文件路径类似于传统对象存储中的对象键（ObjectKey）。您可以根据业务需求自定义文件路径。

说明

  • 文件路径必须包含文件后缀，例如 .mp4，但不要求必须包含文件前缀。
  • 最大长度不超过 1024 个字符。
  • 详细的字符规则，请见文件命名通用字符规则。
  • 如果设置了 FileName，请确保不同文件具有不同的 FileName，以避免文件覆盖的风险。
  • 传入 FileName 后，无需再传入FileExtension 参数。
SourceUrl
String
否
https://demourl
源文件 URL。
Templates
Object[]
否
-
工作流信息。上传完成后如果希望自动触发媒体处理工作流，可传入此参数。
TemplateIds
String[]
否
["abcd***123"]
工作流 ID。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。当前仅支持单个工作流 ID。
TemplateType
String
否
transcode

工作流类型。取值如下：

  • transcode: （默认）在视频点播服务中创建的工作流。
  • imp: 在智能处理服务中创建的工作流。
TemplateId
String
否
25524a2dae45***b2e891d7daf4b9

工作流 ID。上传完成后如果希望自动触发媒体处理工作流，可传入此参数。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。

注意

TemplateId 已废弃，推荐使用 Templates 参数。

Description
String
否
视频测试
文件描述。不超过 256 个字符。
CallbackArgs
String
否
YourCallbackArgs
用户额外信息。回调时会透传返回，最大长度 512 字节。
StorageClass
Integer
否
1

存储类型。默认为 1。取值如下：

  • 1：标准存储。
  • 2：归档存储。
  • 3：低频存储。
FileExtension
String
否
.m3u8

文件后缀，即点播存储中文件的类型。

说明

  • 文件后缀必须以 . 开头，不超过 8 位。
  • 当您传入 FileExtension 时，不需要重复传入 FileName 参数。视频点播将生成 32 位随机字符串，和您传入的 FileExtension 共同拼接成文件路径。
ClassificationId
Long
否
6708

音视频的分类 ID。音视频的分类是由您自行创建并管理的，方式如下：

CustomURLHeaders
JSONMap
否
User-Agent:Mozilla/4.0

自定义对源视频 URL 访问请求的 URL Header。格式为 "key":"value"。

  • "key"： String 类型，访问源视频 URL 携带的 HTTP Header 的 key。示例：User-Agent。
  • "value"： String 类型，访问源视频 URL 携带的 HTTP Header 的 value。示例：Mozilla/4.0。
EnableLowPriority
Boolean
否
false

是否开启闲时转码。取值如下：

  • true：开启。
  • false：（默认）关闭。

说明

对于闲时转码的介绍和使用场景，请见闲时转码。

UrlEncryptionAlgorithm
String
否
DES

源 URL 加密方法。目前支持的取值为 DES，表示 PCKS5Padding 加密。

注意

加密方法必须与文件后缀一起传入。您可以选择在 FileName 中包含后缀，或者通过传入 FileExtension 参数来指定后缀。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数
类型
示例值
描述
Data
Object[]
-
URL 和对应 JobId 的结构数组。
SourceUrl
String
https://demourl.mp4
源文件 URL。
JobId
String
db3ab211095******b0955a30b550
URL 对应的 ID。可用于查询上传状态。

请求示例

https://vod.volcengineapi.com?Action=UploadMediaByUrl&Version=2020-08-01
{
    "SpaceName": "test",
    "URLSets": [
        {
            "Tags": "tag1",
            "Title": "demo",
            "FileName": "example.mp4",
            "SourceUrl": "https://demourl",
            "Templates": [
                {
                    "TemplateIds": [
                        "abcd***123"
                    ],
                    "TemplateType": "transcode"
                }
            ],
            "Description": "视频测试",
            "CallbackArgs": "YourCallbackArgs",
            "StorageClass": 1,
            "ClassificationId": 6708,
            "EnableLowPriority": true
        }
    ]
}

返回示例

{
  "ResponseMetadata": {
    "RequestId": "20201102******2250910621303DE51",
    "Action": "UploadVideoByUrl",
    "Version": "2022-12-01",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": {
    "Data": [
      {
        "JobId": "db3ab211095******b0955a30b550",
        "SourceUrl": "https://demourl.mp4"
      }
    ]
  }
}

错误码

下表列举了本接口特有的错误码。如需了解更多错误码，详见视频点播公共错误码。

状态码错误码错误信息说明

400

InvalidParameter.UploadParamsError

-必须字段错误，可以根据提示信息判断参数为空的具体字段。

  • 参数类型错误，可以根据提示信息判断参数类型是否正确。
400InvalidParameter.AKMissMatchError-参数错误，账号无权限。
500InternalError.QueryBodyError-内部错误，查询 JobId 失败。
400InvalidParameter.JobIdEmptyError-参数错误，JobIds 字段为空。
400InvalidParameter.TitleLengthError-参数错误，Title 字段超过 128个字符。
400InvalidParameter.DescriptionLengthError-参数错误，Description 字段超过 256个字符。
400InvalidParameter.CategoryLengthError-参数错误，Category 字段超过 256个字符。
400InvalidParameter.TagsLengthError-参数错误，Tags 字段超过 36个字符。
400InvalidParameter.BodyParseError-参数错误，传入的参数格式错误。
500InternalError.CreateUploadStateError-内部错误，创建 URL 上传记录失败。
500InternalError.BuildRavenDataError-内部错误，创建内部消息失败。
500InternalError.NsqSendError-内部错误，发送消息失败。
500InternalError.GetAccountError-内部错误，获取账号信息失败。
400InvalidParameter.SpaceNotExistsError-参数错误，空间不存在。
403RequestForbidden.AccessIsRestricted-账号访问受到限制。
400InvalidParameter.InvalidFileExtensionStyle-文件后缀格式错误。

服务端 SDK

点播 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API，此 API 各语言调用的示例代码，请参考如下：