申请上传
更新时间：2024-12-17
VOD不提供直接创建媒资的API接口，而是用申请上传、上传文件、完成上传三步创建法完成创建：
- 通过申请上传获取sessionKey、上传链接；
- 通过上传链接上传音视频文件；
- 通过完成上传通知VOD服务文件上传完毕，VOD生成媒资。
通过本接口可以获取媒资上传时的唯一标识sessionKey和上传链接，sessionKey会在完成上传时用于校验文件。
sessionKey有效期为24小时，需在有效期内完成上传文件和完成上传请求，否则相应的sessionKey将逾期失效。若已上传文件但未请求完成上传，则该文件将会在一天后自动清理。
文件上传可以分为简单上传和分片上传两种方式，简单上传适用于大部分情况（单个文件不超过5GB），分片上传适用于大文件上传。
请求结构
POST /v2/medias/upload HTTP/1.1
connection: keep-alive
host: vod.bj.baidubce.com
content-type: application/json
x-bce-request-id: <bce-request-id>
x-bce-date: <utc-date-string>
authorization: <bce-authorization-string>
{
// 请求参数
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| name | string | 是 | RequestBody参数 | 名称 |
| container | string | 是 | RequestBody参数 | 音视频、图片封装格式，支持的文件封装格式（文件扩展名）：
|
| isMultipartUpload | boolean | 否 | RequestBody参数 | 是否需要分片上传，默认简单上传为false，分片上传为true |
| numParts | int | 否 | RequestBody参数 | 分片数，isMultipartUpload为true时必须指定 |
返回头域
除公共头域，无其它特殊头域。
返回参数
| 参数 | 类型 | 描述 |
|---|---|---|
| sessionKey | string | 临时上传key |
| urls | string[] | 上传预签名链接，使用HTTP PUT上传文件到此地址 |
示例
申请简单上传
请求内容
POST /v2/medias/upload HTTP/1.1
host: vod.bj.baidubce.com
accept: */*
connection: keep-alive
content-type: application/json
x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481
x-bce-date: 2024-03-24T13:08:44Z
authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2024-03-24T13:08:44Z/1800/host;x-bce-date/7e21c9cf1e4e2cc6921a407a388fe98df122c53b9f509043d841be76eb09a1f9
{
"name": "demo",
"isMultipartUpload": false,
"container": "mp4"
}返回内容
HTTP/1.1 200 OK
Transfer-Encoding: chunked
x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481
Cache-Control: no-cache
Date: Tue, 24 Mar 2024 13:08:44 GMT
Content-Type: application/json;charset=UTF-8
{
"urls": [
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcswd3qq16w6ftkb34d.mp4?authorization=xxx"
],
"sessionKey": "ZEcxd0wyVm9jblIwTlhCemNYSnphbWxsWXpkNFpXbDJMMlZ0WTNOM1pETnhjVEUyZHpabWRHdGlNelJrTG0xd05BPT1fX1pHVnRidz09"
}获取到上传链接后，可以使用HTTP PUT方法上传文件，以curl方式举例：
curl -i -X PUT 'https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs6vuzwhwhv00397qq.mp4?authorization=xxx' \
-H 'Content-Type: video/mp4' \
--data-binary '@/path/to/demo.mp4'执行以上命令，得到输出类似以下内容，则表示上传成功，下一步可以请求完成上传创建媒资。
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Tue, 03 Dec 2024 09:01:49 GMT
Content-Length: 0
Connection: keep-alive
Content-MD5: 4gA7ok7QQ35GUKKsJbcMXA==
ETag: "e2003ba24ed0437e4650a2ac25b70c5c"
Server: BceBos
x-bce-content-crc32: 2470501973
x-bce-debug-id: n5RKu+pc5wkwcvUuj+mAZrBVusdZ56Znr0jmzNR9J3OsjIWLBnOxbiyuaSsuo7dqtzfVZtfOQLlHkxitMwPzdw==
x-bce-flow-control-type: -1
x-bce-is-transition: false
x-bce-request-id: 29235247-d5a8-45ca-8381-746f25c549f8申请分片上传
请求内容
POST /v2/medias/upload HTTP/1.1
host: vod.bj.baidubce.com
accept: */*
connection: keep-alive
content-type: application/json
x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481
x-bce-date: 2024-03-24T13:08:44Z
authorization: bce-auth-v1/46bd9968a6194b4bbdf0341f2286ccce/2024-03-24T13:08:44Z/1800/host;x-bce-date/7e21c9cf1e4e2cc6921a407a388fe98df122c53b9f509043d841be76eb09a1f9
{
"name": "demo",
"isMultipartUpload": true,
"numParts": 10,
"container": "mp4"
}返回内容
HTTP/1.1 200 OK
Transfer-Encoding: chunked
x-bce-request-id: 6bae5cb3-97d1-4b1a-b8b6-0ad577c1d481
Cache-Control: no-cache
Date: Tue, 24 Mar 2024 13:08:44 GMT
Content-Type: application/json;charset=UTF-8
{
"urls": [
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=1&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=2&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=3&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=4&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=5&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=6&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=7&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=8&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=9&authorization=xxx",
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=10&authorization=xxx"
],
"sessionKey": "ZEcxd0wyVm9jblIwTlhCemNYSnphbWxsWXpkNFpXbDJMMlZ0WTNNd2FIcG1aV05vZEdoM056TmphRFo2TG0xd05BPT1fX1pHVnRidz09X19ZemhrWmpVek0yUTFZelpqTm1Rd09XWmpNV0UwTW1SbE1XSXhOelUxTXpCQg"
}获取到分片上传链接后，需要将待上传的文件进行切分，再分别进行PUT方法上传文件分片，注意需要记录上传请求的响应头中的Etag，Etag信息在完成上传请求中会被使用。
下面以一个大视频文件的分片上传来举例说明:
测试文件为large_file.mp4，大小为10GB，切分为10片，使用上面申请分片上传请求返回的urls进行分片上传，并记录每个分片的Etag。
测试脚本如下，脚本的基本逻辑是：
- 使用split命令将大文件切分为10个分片
- 使用curl命令上传每个分片，并记录返回的Etag
- 将所有分片的Etag封装为JSON格式，用于后续完成上传请求
#!/bin/bash
# 文件路径和分片目录
large_file="/path/to/large_file.mp4"
split_dir="split_parts"
num_parts=10
# 模拟分片上传URL数组
urls=(
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=1&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=2&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=3&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=4&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=5&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=6&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=7&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=8&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=9&authorization=xxx"
"https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcs0hzfechthw73ch6z.mp4?uploadId=c8df533d5c6c6d09fc1a42de1b175530A&partNumber=10&authorization=xxx"
)
# 检查分片目录是否存在
if [ -d "$split_dir" ]; then
rm -rf "$split_dir"
fi
mkdir -p "$split_dir"
# 第一步：分片操作
echo "Splitting file into $num_parts parts..."
split -n $num_parts -d "$large_file" "$split_dir/part_"
# 初始化ETag数组
etags=()
# 上传每个分片并获取ETag
for i in "${!urls[@]}"; do
part_number=$(printf "%02d" $i) # 生成与文件名匹配的编号，如 00, 01, ...
part_file="${split_dir}/part_${part_number}"
url="${urls[$i]}" # 直接对应 URL 数组索引
echo "Uploading part: $part_file to $url"
response=$(curl -si -X PUT --data-binary @"$part_file" "$url")
etag=$(echo "$response" | grep -i "ETag" | awk -F '"' '{print $2}')
if [ -n "$etag" ]; then
etags[$i]="$etag"
echo "ETag for $part: $etag"
else
echo "Failed to get ETag for $part"
etags[$i]=""
fi
done
etags_json=$(printf ",\"%s\"" "${etags[@]}" | sed 's/^,//')
echo -e "Got ETags:\n{ \"etags\": [$etags_json] }"
# 清理临时文件
rm -rf "$split_dir"执行脚本的输出是：
Splitting file into 10 parts...
Uploading part: split_parts/part_00 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=1&authorization=xxx
ETag for : ac71b3427eee9461f16b552cc85d0334
Uploading part: split_parts/part_01 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=2&authorization=xxx
ETag for : 247cdd2cb2e5765a8f85799959ea11dc
Uploading part: split_parts/part_02 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=3&authorization=xxx
ETag for : c49456c5d76e2d141a1f0d1e221f25bb
Uploading part: split_parts/part_03 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=4&authorization=xxx
ETag for : 0df12352e5bf046fa59e971d0c4c9722
Uploading part: split_parts/part_04 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=5&authorization=xxx
ETag for : 8e0f858db29fcefc0f8749f2d8cf7fcf
Uploading part: split_parts/part_05 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=6&authorization=xxx
ETag for : 0cf3988a4f068ece8f4d48349e8a0cd0
Uploading part: split_parts/part_06 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=7&authorization=xxx
ETag for : d1eb02748aa6639436df37e3bc5562eb
Uploading part: split_parts/part_07 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=8&authorization=xxx
ETag for : a0bd82db71c0a91c29101d573a6beff8
Uploading part: split_parts/part_08 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=9&authorization=xxx
ETag for : 4465bd610b59abce5b22ddf7db1565fb
Uploading part: split_parts/part_09 to https://bj.bcebos.com/v1/vod-xxx/tmp/ehrtt5psqrsjiec7xeiv/emcv4sg2q1qb4be1s8ev.mp4?uploadId=9243ffc5a2cfc6a4bcc7b9e8413f4babA&partNumber=10&authorization=xxx
ETag for : a52d0331e51eb3f83ee66b08f7b739cf
{ "etags": ["ac71b3427eee9461f16b552cc85d0334","247cdd2cb2e5765a8f85799959ea11dc","c49456c5d76e2d141a1f0d1e221f25bb","0df12352e5bf046fa59e971d0c4c9722","8e0f858db29fcefc0f8749f2d8cf7fcf","0cf3988a4f068ece8f4d48349e8a0cd0","d1eb02748aa6639436df37e3bc5562eb","a0bd82db71c0a91c29101d573a6beff8","4465bd610b59abce5b22ddf7db1565fb","a52d0331e51eb3f83ee66b08f7b739cf"] }得到上传完成的etags，接下来可以使用这些etags和sessionKey来作为完成上传请求的输入参数。
错误码
详见公共错误返回。