tencent cloud

Smart Media Hosting

Product Introduction
Product Overview
Feature Description
Product Strengths
Use Cases
Basic Concept
Purchase Guide
Quick Start
Create Media Library
Initiate request
Service Level API Document
History
Introduction
API Category
Making API Requests
PaaS Service APIs
Official Cloud Disk APIs
Data Types
Error Codes
Business Level API Document
Introduction
Access Token Operation API
Tenant Space Operation API
File Operation API
Directory or Album Operation API
Recycle Bin Operation API
Quota Operation API
Query Task Operation API
Search Operation API
Historical Version Operations API
Directory and File Batch Operation API
Collection Operation API
Error Codes
SDK Documentation
Android SDK
iOS SDK
HarmonyOS SDK
FAQs
Enterprise Network Disk
Product Introduction
Purchase Guide
Quick Start
FAQs
Service Level Agreement
Glossary
DocumentationSmart Media HostingBusiness Level API DocumentFile Operation APIUpload a file in parts

Upload a file in parts

PDF
Focus Mode
Font Size
Last updated: 2026-01-07 14:15:05

Description

Start a multipart upload.
Note:
Required permissions: admin, space_admin, or upload_file/upload_file_force/begin_upload/begin_upload_force. For details on permissions, see Generate Access Token Interface.
Multipart upload refers to uploading a file in parts using HTTP PUT requests, completing the entire file upload through multiple uploads, with each request body containing a single part of the file content.
Calling this API returns a set of parameters for multipart upload requests and confirming the completion of the upload. The target URL for upload is https://{Domain}{Path}?uploadId={UploadId}&partNumber={PartNumber}, where Domain is the domain field in the response body, Path is the path field in the response body, UploadId is the uploadId field in the response body, and PartNumber is the part number starting from 1, for example https://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/smhxxx/xxx.mp4?uploadId=xxx&partNumber=1.
For PUT simple upload, a series of additional request header fields must be specified. The names and values of these fields are included in the headers field of the response body.
When using JS to upload files in the browser, you need to configure Cross-Origin Resource Sharing (CORS) in the bound COS bucket in advance.
After the actual upload completes, HTTP 200 OK will be returned by the target URL.
Unlike multipart uploads in COS, SMH multipart uploads do not require recording eTags or passing them during upload completion. Simply ensure consecutive part uploads, and SMH will automatically perform these operations when completing the file upload.
By default, files with the same name will be automatically renamed. The final file path can be obtained from the interface for file upload completion.
It does not automatically create the required parent directories, so you must ensure that all levels of directories in the path exist.
Media libraries of media type do not support uploading files with file extensions.

Request

Request Example

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}`

Request Parameter

Request parameters.
Description
Type
Required or Not
LibraryId
Media Library ID, obtain it after creating a media library in the media hosting console, see Create Media Library
String
Yes
SpaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as a hyphen (`-`). If the media library is in multi-tenant mode, you must specify this parameter. See Create Tenant Space
String
No
FilePath
Complete file path, such as foo/bar/file.docx. See View directory or album
String
Yes
FileSize
Upload file size in bytes to check if available space is sufficient.
String
No
ConflictResolutionStrategy
Handling method when filename conflict, default is rename
ask: returns HTTP 409 Conflict and SameNameDirectoryOrFileExists error code when conflicts with
rename: automatically rename file when conflicts with
overwrite:
If the target is a directory or album, it defaults to ask and does not support overwrite
If the target is a file, overwrite the existing file
When a file exists in the target space with an earlier version, moving to overwrite is not supported.
String
No
AccessToken
Access token, see Generate Access Token
String
Yes
UserId
User identity recognition. When the access token has admin permission and the user identity recognition during token application is empty, it is used to temporarily specify user identity. For details, see Generate Access Token API.
String
No
TrafficLimit
Single-link download speed limit, range 100KB/s - 100MB/s, Unit B
Number
No
PreferSameOrigin
Whether to keep the same domain name, valid values: true or false
This parameter is valid only when files with the same name exist in the upload file path and ConflictResolutionStrategy is set to rename or overwrite
When this parameter is set, the backend will try to ensure that newly uploaded files and the original file use the same domain name for upload or download, but in special cases, different domain names may still be used, so you should not rely too much on this parameter.
Boolean
No

Request Header

x-smh-meta-*: custom metadata.

Request Body

{
  "fullHash": "9fee55123adad49e5090236eead6a8a9edc9caaa0f97b9e38c3713c1b97b9d29",
  "beginningHash": "9faskdfhwek2h3r4kjdsjkahfsdkfhjaksdldc9caaa0f97b9e38c3713c1b97b9d29",
  "size": "2081112",
  "labels":["elephant","animal","Asian elephant"],
  "category":"video",
  "localCreationTime": "2022-07-26T02:58:09Z",
  "localModificationTime": "2022-07-26T02:58:09Z"
}
Request parameters.
Description
Type
Required or Not
beginningHash
The fullHash value of the first 1MB of the file, used for instant upload: the sha256 hash value of the first 1MB of the file.
String
No
fullHash
The fullHash value of the file defined by SMH, used for instant upload. The following algorithm:
Fetch the first 1MB of the file, compute sha256, and use the result as both beginningHash and fullHash.
Continue fetching the next 1MB segment of the file, compute fullHash and the sha256 of the current 1MB data, sha256(Buffer.concat([Buffer.from(fullHash, 'hex'), contentBuffer])), and use the result as fullHash.
Compute until all is done to get fullHash
String
No
size
File size for instant upload: Files with size >= 1MB can achieve instant upload.
String
No
labels
File Tag List
String Array
No
category
Customized File Categories
String
No
localCreationTime
File local creation time
String
No
localModificationTime
File local modification time
String
No

Response

Response code

Upload task created successfully, return HTTP 201 Created.
beginningHash matches the instant upload file, return HTTP 202 Accepted.
fullHash matches the instant upload file, return HTTP 200 OK.

Response Body

application/json
Response body example (when it does not meet the instant upload condition):
{
    "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
}
Response body field description:
Response Parameters
Description
Type
domain
Domain name during actual file upload
String
path
URL path during actual file upload, fixed as "/" in form upload
String
uploadId
Request parameters to be specified during actual file upload
String
headers
Request header to be specified during actual upload
String
confirmKey
Parameters for completing file upload
String Array
expiration
The valid period of upload information will become invalid if it exceeds the validity period. You must call this API again to get new upload parameters.
String
availableDomainNum
Number of available domains
String
Response body example (when beginningHash matches the instant upload condition): return 202 with an empty response body.
Response body example (when fully meeting the instant upload condition):
{
  "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"
}
Response field description:
Response Parameters
Description
Type
path
If it is a string array, it indicates the final file path. The last element in the array represents the final file name, and the other elements represent each first-level directory name. Because existing files with the same name may be renamed automatically, the final path here may not equal the designated path when uploading started.
If it is null, it means that the directory where the file resides or a certain parent directory has been deleted, and the file can no longer be accessed.
String Array
name
Final file name
String
type
File type
String
creationTime
Time of first upload completion
String Array
modificationTime
Last overwrite time of the file
String
contentType
media type
String
size
File size.
String
eTag
File eTag
String
crc64
File CRC64-ECMA182 check value
String
metaData
metadata, if there is no metadata then this field does not exist
String
isOverwritten
Whether file overwrite occurred during file upload
Boolean
previewByDoc
Whether WPS can be used to preview
Boolean
previewByCI
Whether Wanxiang can be used to preview
Boolean
previewAsIcon
Use preview image as icon
Boolean
fileType
File type: Excel, PowerPoint
String

Error Codes

This request operation has no special error messages. For common error messages, see Error Codes.
Previous Topic: Simple upload of fileNext Topic: Renew a Multipart Upload Task

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback