文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>智能媒资托管>业务级 API 文档>文件操作接口>分块上传文件

分块上传文件

最近更新时间：2025-10-29 14:34:31

我的收藏

本页目录：

功能描述

用于开始分块上传文件。
说明：
要求权限：admin、space_admin 或 upload_file/upload_file_force/begin_upload/begin_upload_force。有关权限详情请参见 生成访问令牌接口。
分块上传指使用 HTTP PUT 请求上传一个文件的分块，通过多次上传完成整个文件的上传，每次请求的请求体为文件内容的单个分块。
调用该接口将返回一系列用于分块上传请求和确认上传完成的参数，上传的目标 URL 为 https://{Domain}{Path}?uploadId={UploadId}&partNumber={PartNumber}，其中 Domain 为响应体中的 domain 字段，Path 为响应体中的 path 字段，UploadId 为响应体中的 uploadId 字段，PartNumber 为从 1 开始的分块顺序，例如 https://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/smhxxx/xxx.mp4?uploadId=xxx&partNumber=1。
上传每个分块时还需要指定一系列额外的请求头部字段，这些字段的名和值包含在响应体中的 headers 字段中。
当在浏览器使用 JS 上传文件时，需要提前在绑定的 COS 存储桶中设置 跨域访问（CORS）。
在完成实际上传后，上传的目标 URL 将返回 HTTP 200 OK。
与对象存储的分块上传不同，SMH 的分块上传无需记录 eTag，也无需在完成上传时传入这些 eTag，只需保证上传分块的连续即可，SMH 将在 完成文件上传 时自动执行这些操作。
默认情况下同名文件将自动修改文件名，可在完成上传文件接口中获取最终的文件路径。
不会自动创建所需的各级父目录，所以必须保证路径的各级目录存在。
媒体类型的媒体库不支持上传带有文件扩展名的文件。

请求

请求示例

POST /api/v1/file/`{LibraryId}`/`{SpaceId}`/`{FilePath}`?multipart&conflict_resolution_strategy=`{ConflictResolutionStrategy}`&filesize=`{FileSize}`&access_token=`{AccessToken}`&user_id=`{UserId}`&traffic_limit=`{TrafficLimit}`&prefer_same_origin=`{PreferSameOrigin}`

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID，在媒体托管控制台创建媒体库后获取，请参见 创建媒体库
String
是
SpaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(`-`)；如果媒体库为多租户模式，则必须指定该参数，获取请参见 创建租户空间
String
否
FilePath
完整文件路径，例如 foo/bar/file.docx。获取请参见 查看目录或相簿
String
是
FileSize
上传文件大小，单位为字节（Byte），用于判断剩余空间是否足够
String
否
ConflictResolutionStrategy
文件名冲突时的处理方式，默认为 rename
ask：冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename：冲突时自动重命名文件
overwrite：
如果目标为目录或相簿时，默认为 ask 且不支持 overwrite
如果目标为文件，覆盖已有文件
当目标空间的文件存在历史版本时，不支持移动覆盖
String
否
AccessToken
访问令牌，获取请参见 生成访问令牌
String
是
UserId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份，详情请参见 生成访问令牌接口
String
否
TrafficLimit
单链接下载限速，范围100KB/s - 100MB/s，单位B
Number
否
PreferSameOrigin
是否倾向于保持相同域名，可能的值为 true 或 false：
此参数仅当上传文件的路径存在同名文件，且 ConflictResolutionStrategy 设置为 rename 或 overwrite 时生效
当设置此参数时，后台会尽量保证新上传的文件与原文件使用相同的域名进行上传或下载，但在特殊情况下仍有可能使用不同域名，因此不应过于依赖此参数
Boolean
否

请求头部

x-smh-meta-*：自定义元数据。

请求体

{
  "fullHash": "9fee55123adad49e5090236eead6a8a9edc9caaa0f97b9e38c3713c1b97b9d29",
  "beginningHash": "9faskdfhwek2h3r4kjdsjkahfsdkfhjaksdldc9caaa0f97b9e38c3713c1b97b9d29",
  "size": "2081112",
  "labels":["大象","动物","亚洲象"],
  "category":"video",
  "localCreationTime": "2022-07-26T02:58:09Z",
  "localModificationTime": "2022-07-26T02:58:09Z"
}
请求参数
描述
类型
是否必选
beginningHash
文件前1M的 fullHash 值，用于秒传：文件开头1M的 sha256 哈希值
String
否
fullHash
SMH 定义的文件的 fullHash 值，用于秒传，具体算法如下：
取出文件前1MB内容，计算 sha256，结果同时作为 beginningHash 和 fullHash
继续取出文件下一段1MB内容，计算 fullHash 和当前的1MB数据的 sha256，sha256(Buffer.concat([Buffer.from(fullHash, 'hex'), contentBuffer]))，结果作为 fullHash
直到全部算完，得到 fullHash
String
否
size
文件大小，用于秒传：size >= 1M 的文件才能实现秒传
String
否
labels
文件标签列表
String Array
否
category
文件自定义的分类
String
否
localCreationTime
文件对应的本地创建时间
String
否
localModificationTime
文件对应的本地修改时间
String
否

响应

响应码

上传任务创建成功，返回 HTTP 201 Created。
beginningHash 匹配秒传文件，返回 HTTP 202 Accepted。
fullHash 匹配秒传文件，返回 HTTP 200 OK。

响应体

application/json
响应体示例（不符合秒传条件时）：
{
    "domain": "examplebucket-1250000000.cos.ap-beijing.myqcloud.com",
    "path": "/smhxxx/xxx.mp4",
    "uploadId": "xxx",
    "headers": {
        "Content-Type": "application/octet-stream",
        "Authorization": "q-sign-algorithm=sha1&xxxxxx",
        "x-cos-security-token": "1dleQZoBrm4i5UKcV1ovQM4f63aE3Ldaa508aa686f404316d3628xxx",
        "x-cos-traffic-limit": 204800
    },
    "confirmKey": "7e8481cea3beecbfe5374c904ca9e7496abc612f400c323877310198745270b0",
    "expiration": "2021-07-24T10:34:32.000Z",
    "availableDomainNum":1
}
响应体字段说明：
响应参数
描述
类型
domain
实际上传文件时的域名
String
path
实际文件上传时的 URL 路径，表单上传中固定为"/"
String
uploadId
实际文件上传时需指定的请求参数
String
headers
实际上传时需指定的请求头部
String
confirmKey
用于完成文件上传的确认参数
String Array
expiration
上传信息有效期，超过有效期后将失效，需要重新调用本接口获取新的上传参数
String
availableDomainNum
可用域名数量
String
响应体示例（beginningHash 匹配秒传条件时）：返回 202 响应体为空。
响应体示例（完全符合秒传条件时）：
{
  "path": [
    "test.xlsx"
  ],
  "name": "test.xlsx",
  "type": "file",
  "creationTime": "2022-04-08T08:44:59.000Z",
  "modificationTime": "2022-04-08T08:44:59.000Z",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": "2811086",
  "eTag": "\\"b581c674266a2b0ff16a9505b4c52300\\"",
  "crc64": "16293198345556339838",
  "metaData": {},
  "isOverwritten": false,
  "previewByDoc": true,
  "previewByCI": true,
  "previewAsIcon": false,
  "fileType": "excel"
}
响应字段说明：
响应参数
描述
类型
path
如果是字符串数组则表示最终的文件路径，数组中的最后一个元素代表最终的文件名，其他元素代表每一级目录名，因为可能存在同名文件自动重命名，所以这里的最终路径可能不等同于开始上传时指定的路径
如果是 null 则表示该文件所在的目录或其某个父级目录已被删除，该文件已经无法访问
String Array
name
最终文件名
String
type
文件类型
String
creationTime
文件首次完成上传的时间
String Array
modificationTime
文件最近一次被覆盖的时间
String
contentType
媒体类型
String
size
文件大小
String
eTag
文件 eTag
String
crc64
文件的 CRC64-ECMA182校验值
String
metaData
元数据，如果没有元数据则不存在该字段
String
isOverwritten
文件上传时是否发生文件覆盖
Boolean
previewByDoc
是否可通过 WPS 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图作为 icon
Boolean
fileType
文件类型：Excel、PowerPoint 等
String

错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
中国站
目录