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