MeBox/115doc/115开放平台/API列表/文件管理/文件上传/文件上传.md

文件上传

基本信息

属性	内容
接口名称	文件上传
接口版本	v1.0
接口路径	/upload/init
请求方法	POST
接口状态	生产环境

接口说明

初始化断点续传调度，完成秒传判定、二次认证调度或返回对象存储上传参数。

接口地址

https://proapi.115.com/open/upload/init

请求方式

POST
Content-Type: multipart/form-data

认证方式

Authorization: Bearer access_token

请求参数

参数名	类型	必填	默认值	说明	约束/示例
file_name	string	是	-	文件名	图片.jpg
file_size	int	是	-	文件大小，单位为字节	5335
target	string	是	-	文件上传目标	U_1_0，格式为 U_1_<文件夹ID>
fileid	string	是	-	文件 SHA1 值	<FILE_SHA1>
preid	string	否	""	文件前 128 KiB 内容的 SHA1 值	<PREID_SHA1>
path	string	否	""	上传路径	""
pick_code	string	否	""	上传任务唯一标识，用于续传	<PICK_CODE>
topupload	int	否	""	上传调度文件类型标记，见下方枚举表格	0
sign_key	string	否	""	二次认证标识	<SIGN_KEY>
sign_val	string	否	""	根据 sign_check 计算的大写 SHA1 值	<SIGN_VAL>

请求参数中的 topupload 字段枚举

值	说明	备注
-1	没有上传调度文件类型标记	-
0	单文件上传任务，记录一条独立上传记录	-
1	文件夹任务的第一个子文件，记录一次文件夹上传	-
2	文件夹任务的其他子文件，不单独记录上传记录	-

请求示例

curl 'https://proapi.115.com/open/upload/init' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -F 'file_name=图片.jpg' \
  -F 'file_size=5335' \
  -F 'target=U_1_0' \
  -F 'fileid=<FILE_SHA1>' \
  -F 'topupload=0'

响应字段说明

字段	类型	描述
state	boolean	状态码，是表示成功，否表示异常
message	string	异常信息
code	int	异常码
data	object	上传调度数据
data.status	int	上传状态：1-非秒传 2-秒传
data.code	int	上传调度状态码
data.pick_code	string	上传任务唯一标识，用于续传
data.target	string	文件上传目标
data.bucket	string	对象存储 bucket
data.object	string	OSS 对象标识
data.callback	object	上传完成回调数据
data.callback.callback	string	上传完成回调信息
data.callback.callback_var	string	上传完成回调参数
data.sign_key	string	本次二次认证的 SHA1 标识
data.sign_check	string	二次认证所需本地文件 SHA1 计算的字节范围
data.file_id	string	秒传成功时新增文件 ID

响应示例

{
  "state": true,
  "message": "",
  "code": 0,
  "data": {
    "status": 1,
    "code": 0,
    "pick_code": "",
    "target": "U_1_0",
    "bucket": "",
    "object": "",
    "callback": {
      "callback": "",
      "callback_var": ""
    },
    "sign_key": "",
    "sign_check": "",
    "file_id": ""
  }
}

业务规则

• target 必须匹配 U_1_<数字文件夹ID>；U_1_0 表示网盘根目录。
• 非 VIP 用户单文件大小不得超过 5 GiB；尝鲜VIP、体验VIP用户单文件大小不得超过 15 GiB。
• 上传前会检查用户剩余空间和盗播上传封禁状态。
• 二次认证调度结果见下表。

code	status	说明	后续处理
700	6	签名认证后失败	按 sign_check 截取包含起止字节的文件内容计算大写 SHA1，再传入 sign_key 和 sign_val
701	7	需要认证签名	按 sign_check 截取包含起止字节的文件内容计算大写 SHA1，再传入 sign_key 和 sign_val
702	8	签名认证失败	按 sign_check 截取包含起止字节的文件内容计算大写 SHA1，再传入 sign_key 和 sign_val

注意事项

• sign_check 格式为 起始字节-结束字节，起止字节均包含在 SHA1 计算范围内；例如 2392148-2392298 需计算该范围内文件内容的 SHA1。
• 省略 topupload 时，服务端会将其归一化为空字符串；显式传入枚举值时会归一化为整数。
• 请妥善保管 access_token、上传凭证与回调数据，不要在日志或客户端可见信息中输出。

修改历史

修改时间	修改说明
2025年04月01日(周二) 00:00:00	创建文档