媒资上传模块主要展示通过服务端 API 进行文件上传的 API 调用、回调和代码示例（含断点续传）。

除服务端 API 调用上传外，您也可通过登录 网易云信控制台 进行网页上传，或接入 上传 SDK 进行上传。

媒资上传初始化

用于媒资上传的初始化，查询 xNosToken（上传凭证）、bucket（存储对象的桶名）、object（生成的唯一对象名）。

接口描述

• 域名：vcloud.163.com

• 接口名：/app/vod/upload/init

输入参数

参数	类型	是否必需	说明
originFileName	String	是	上传文件的原始名称（包含后缀名）。
userFileName	String	否	用户命名的上传文件名称。
typeId	Int	否	视频所属的类别 ID（不填写为默认分类）。
presetId	Int	否	视频所需转码模板 ID（不填写为默认模板，默认模板不进行转码）。
uploadCallbackUrl	String	否	上传成功后回调客户端的 URL 地址（需标准 http 格式）。
callbackUrl	String	否	转码成功后回调客户端的 URL 地址（需标准 http 格式）。
description	String	否	上传视频的描述信息。
watermarkId	Int	否	视频水印 ID（不填写为不添加水印，如果选择， 请务必在水印管理中提前完成水印图片的上传和参数的配置。 且必需设置 prestId 字段，且 presetId 字段不为默认模板）。
userDefInfo	String	否	用户自定义信息，回调会返回此信息（长度不能超过 256 字符）。
transOffset	Int	否	视频转码处理裁剪视频的起始位置，必需设置 prestId 字段且 presetId 字段不为默认模板才有效（单位：秒）。
transDuration	Int	否	视频转码处理裁剪视频的视频时长，必需设置 prestId 字段且 presetId 字段不为默认模板才有效（单位：秒）。

输出参数

参数	类型	说明
code	Int	状态码。
xNosToken	String	上传凭证。
bucket	String	存储上传文件的桶名。
object	String	存储上传文件的对象名。
msg	String	错误信息。

响应状态码

状态码	说明
200	操作成功。
400	请求报文格式错误，报文构造不正确或者没有完整发送。
700	服务器内部出现错误，请稍后重试或者将完整错误信息 提交工单 联系网易云信技术支持工程师。
710	权限认证失败，请参考文档中的接口鉴权部分。
720	访问失败，余额不足。
721	服务未开通，请前往开通页面申请服务开通。
722	服务开通审核中，请 提交工单 联系网易云信技术支持工程师。
723	请求的次数超过了配额限制。

请求示例（cURL）

cURLcurl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338b***af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028***7ae13" -d'{"originFileName":"love.mp4","userFileName":"for_love.mp4","typeId":20,"presetId":20,"description":"for love","wartermarkId":20}' https://vcloud.163.com/app/vod/upload/init

成功返回示例

JSON    "Content-Type": "application/json; charset=utf-8"
    {
        "code" : 200,
        "ret" : {
            "xNosToken" : "UPLOAD ab1856bb****b8e5ee:n5VKrOLVF*****k1NTc5NjU4In0=",
            "bucket" : "vodk32**f",
            "object" : "d37906a7****52ad.mp4"
        }
    }

查询上传地址

用于查询上传加速节点地址。

接口描述

• 域名：http://wanproxy.127.net

• 接口名：/lbs?version=1.0&bucketname={bucket}

输入参数

参数	类型	是否必需	说明
version	String	是	API 版本号，填写固定值 1.0。
bucketname	String	是	存储上传文件的桶名，可在视频上传初始化接口的返回参数 bucket 查询。

输出参数

参数	类型	说明
lbs	String	httpDNS 的 IP 访问地址，用于避免后续查询的 DNS 解析时间、以及域名劫持。
upload	List	上传节点列表（前面的优先级高）。

响应状态码

参数	类型	说明
Code	String	错误代码。
Message	String	错误描述信息。

请求示例（cURL）

cURLcurl -X GET http://wanproxy.127.net/lbs?version=1.0&bucketname=vod**ywxdf

成功返回示例

JSON{
  "lbs": "http://223.252.**.**/lbs",
  "upload": [
    "http://223.252.**.**",
    "http://223.252.**.**"
  ]
}

媒资上传

上传一块数据，此接口通过指定 offset 实现断点续传功能。用户每次上传要以服务器端返回的 offset 为准续传余下数据。

• 支持通过服务端接口或媒体上传 SDK 进行媒资上传。推荐使用媒体上传 SDK 进行媒资上传，具体请参考 媒体上传 SDK。
• 如果上传大文件，请使用分片上传，分片大小不超过 4 MB。请求相同接口，注意参数的填写。
• 如果需要断点续传，需保存 context 值，根据 context 值查询断点值，然后继续使用此接口。
• 包体数据为二进制数据。

接口描述

POST {UploadHost}/{bucket}/{object}

• {UploadHost} 值为查询的上传加速节点地址。
• {bucket} 值为存储对象的桶名。
• {object} 值为生成的唯一对象名。

输入参数

参数	类型	是否必需	说明
x-nos-token	String	是	请求头参数，上传 token。
Content-Length	long	否	请求头参数，当前片的内容长度， 单位：字节（Byte）。Content-Length 合法值是[0~4M]， 否则返回 400 httpcode 给客户端，拒绝本次请求。
Content-Type	String	否	请求头参数，标准 http 头。表示请求内容的类型， 例如：image/jpeg。仅第一次上传生效，续传不生效。
Content-MD5	String	否	请求头参数，文件内容 md5 值。
bucket	String	是	存储对象的桶名。
object	String	是	生成的唯一对象名。
offset	long	是	当前分片在整个对象中的起始偏移量，单位：字节（Byte）。
complete	String	是	是否为最后一块数据。合法值：true/false。
version	String	是	http api 版本号。这里是固定值 1.0。
context	String	是	上传上下文。本字段是只能被上传服务器解读使用的不透明字段， 上传端不应修改其内容。用户第一次上传应不带此参数或置为空字符串， 之后上传剩余部分数据都需要带上这个参数。 context 对应的桶名或者对象名不匹配返回 400 code

响应成功输出参数

参数	类型	是否必需	说明
requestId	String	是	uuid 字符串，服务器端生成的唯一 UUID。
offset	long	是	下一个上传片在上传块中的偏移。偏移从 0 开始，例如：用户上传 0-128 字节后， 服务器返回的 offset 为 128，下一次上传 offset 值应置为 128。
context	String	是	上传上下文。
callbackRetMsg	String	是	上传回调信息。

响应失败输出参数

参数	类型	说明
requestId	String	uuid 字符串，服务器端生成的唯一 UUID。
errMsg	String	错误描述信息。

响应状态码

状态码	说明
200	上传分片成功。
400	请求报文格式错误，报文构造不正确或者没有完整发送。
403	上传凭证无效。token 过期服务器会返回此状态码，用户需要重新申请 token。
500	服务器内部出现错误，请稍后重试或者将完整错误信息 提交工单 联系网易云信技术支持工程师。
520	回调失败。

请求示例（cURL）

cURLcurl -X POST -H "Content-Length: 4194304" -H "x-nos-token: UPLOAD ab1****e5ee:n5VKrOLVFkLM7JI***2OTk1NTc5NjU4In0=" -d'[本次上传视频文件二进制内容数据]' "http://223.252.**.**/vodk32ywxdf/d37906a7-0119-***c66a71952ad.mp4?offset=0&complete=false&version=1.0"

成功返回示例

JSON    {
        "requestId":"be82c2a0****189d831",
        "offset":4194304,
        "context":"f3e2681*****9ff47af21c7",
        "callbackRetMsg":""
    }

查询长传断点

根据上传上下文查询对应分片上传当前续传的 offset，上下文要与 bucketName/objectName 匹配，否则返回 400 状态码。（bucketName 和 objectName 要进行 URL 编码，字符编码格式使用 utf-8）。

接口描述

GET {UploadHost}/{bucket}/{object}?uploadContext

• {UploadHost} 值为查询的上传加速节点地址。
• {bucket} 值为存储对象的桶名。
• {object} 值为生成的唯一对象名。

输入参数

参数	类型	是否必需	说明
x-nos-token	String	是	上传 token。
bucketName	String	是	存储对象的桶名。
objectName	String	是	生成的唯一对象名。
context	String	是	上传上下文。本字段是只能被上传服务器解读使用的不透明字段， 上传端不应修改其内容。对应 context 在服务端不存在则返回 404。 context 对应的桶名或者对象名不匹配返回 400 code。
version	String	是	http api 版本号。这里是固定值 1.0。

响应成功输出参数

参数	类型	是否必需	说明
requestId	String	是	uuid 字符串，服务器端生成的唯一 UUID，用于记录日志排查问题使用。
offset	long	是	下一个上传片在上传块中的偏移。

响应失败输出参数

参数	类型	说明
requestId	String	uuid 字符串，服务器端生成的唯一 UUID。
errMsg	String	错误描述信息。

响应状态码

状态码	说明
200	上传分片成功。
400	请求报文格式错误，报文构造不正确或者没有完整发送。
403	上传凭证无效。token 过期服务器会返回此错误码，用户需要重新申请 token。
500	服务器内部出现错误，请稍后重试或者将完整错误信息 提交工单 联系网易云信技术支持工程师。
404	对应 context 上传不存在。

请求示例（cURL）

cURLcurl -X GET -H "x-nos-token: UPLOAD ab1856bb****4e1b8e5ee:n5VKrOLVFkL****DY2OTk1NTc5NjU4In0=" "http://223.252.**.**/vodk32ywxdf/d37906a7-0119-****71952ad.mp4?uploadContext&context=f3e26818-83****1c7&version=1.0"

成功返回示例

JSON{
    "requestId":"be82c2a****70a189d832",
    "offset":4194304
}

查询媒资 ID

用于视频或水印上传完成后查询主 ID。

接口描述

• 域名：vcloud.163.com

• 接口名：/app/vod/video/query

输入参数

参数	类型	是否必需	说明
objectNames	List	是	上传文件的对象名列表。

输出参数

参数	类型	说明
code	Int	状态码。
list	List	对象名和视频 ID 对应的列表。
list.vid	Long	视频主 ID。
list.imgId	Int	视频水印图片 ID。
list.objectName	String	存储上传文件的对象名。
msg	String	错误信息。

响应状态码

状态码	说明
200	操作成功。
400	请求报文格式错误，报文构造不正确或者没有完整发送。
700	服务器内部出现错误，请稍后重试或者将完整错误信息 提交工单 联系网易云信技术支持工程师。
710	权限认证失败，请参考文档中的接口鉴权部分。
720	访问失败，余额不足。
721	服务未开通，请前往开通页面申请服务开通。
722	服务开通审核中，请 提交工单 联系网易云信技术支持工程师。
723	请求的次数超过了配额限制。

请求示例（cURL）

cURLcurl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338b***af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028***7ae13" -d'{"objectNames":["33cf71b1-*****-d70db07b9685.mp4"]}' https://vcloud.163.com/app/vod/video/query

成功返回示例

JSON"Content-Type": "application/json; charset=utf-8"
{
    "code" : 200,
    "ret" : {
        list : [
            {
                "objectName" : "33cf71b1*****d70db07b9685.mp4",
                "vid" : 1008
            }
        ]
    }
}

上传回调

媒资上传支持上传成功回调通知。回调设置及管理详细见第 5 节：回调管理。

回调内容示例

JSON{
    "name":"snow.mp4",
    "origAddr":"http://vodk32ywxdf.vod.126.net/vodk32ywxdf/b3d****0e0eb09216e.mp4",
    "type":"upload",
    "vid":1022,
    "fileSize": 111233,
    "user_defined":"userId=123456"
}

请以实际收到的 body 字段为准，以下仅为 body 字段示例。

参数	类型	说明
type	String	回调类型，上传回调固定为 upload
vid	Long	视频文件标识。
fileSize	Long	视频文件大小(字节)
name	String	视频文件名称（上传时指定视频名称）。
origAddr	String	视频的播放地址。
warnning	String	视频类型检测结果，例如视频类型和上传指定不一致，mp4 和 flv 类型的视频不适合流媒体播放拖动等。
user_defined	String	用户自定义字段值（上传时设置的值）