The content of this page has been automatically translated by AI. If you encounter any problems while reading, you can view the corresponding content in Chinese.
Help & Documentation>Cloud Object Storage>API Documentation>Object APIs>Multipart upload>Initiate Multipart Upload

Initiate Multipart Upload

Last updated: 2026-06-05 15:13:56

On this page:

Feature Description

The Initiate Multipart Upload API request initiates a multipart upload. After this request is successfully processed, an UploadId is returned for use in subsequent Upload Part requests.
Note: Only the root account or a sub-account authorized with the Initiate Multipart Upload API permission can call this interface.


Authorization Description

Set the action in the authorization policy to cos:InitiateMultipartUpload. View all actions.

Request

Request Example

POST /<ObjectKey>?uploads HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: 0
Authorization: Auth String
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com. Here, <BucketName-APPID> is the bucket name with the APPID suffix, for example, examplebucket-1250000000. For details, see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions. <Region> is the available region of COS. For details, see Regions and Access Domains.
Authorization: Auth String (For details, see Request Signature).

Request Parameter

This API has no request parameters.

Request Header

In addition to using common request headers, this API also supports the following request headers. For details about common request headers, see Common Request Headers.
Name
Description
Type
Required
Cache-Control
Cache directives defined in RFC 2616, to be saved as object metadata.
string
No
Content-Disposition
File name defined in RFC 2616, to be saved as object metadata.
string
No
Content-Encoding
Encoding format defined in RFC 2616, to be saved as object metadata.
string
No
Content-Type
HTTP request content type (MIME) defined in RFC 2616. This header is used to describe the content type of the object to be uploaded, and will be saved as object metadata.
For example, text/html or image/jpeg.
string
Yes
Expires
Cache expiration time defined in RFC 2616, to be saved as object metadata.
string
No
x-cos-meta-[custom suffix]
User-defined metadata header. For example, x-cos-meta-test: test metadata.
Note:
The user-defined metadata header has a fixed format: x-cos-meta-[custom suffix]. The custom suffix supports hyphens (-), digits, and English letters (a to z). Uppercase English letters are converted to lowercase. Other characters, including underscores (_), are not supported.
There is no limit on the number of user-defined metadata headers. The size of a single header is limited to 2 KB. The total size of all x-cos-meta-[custom suffix] headers must not exceed 4 KB.
string
No
x-cos-storage-class
COS storage type. For the enumerated values, see Storage Type. Examples include MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE. Default value: STANDARD.
Enum
No
x-cos-tagging
Tag set of the object. Up to 10 Tags can be set (for example, Key1=Value1&Key2=Value2). The Key and Value in the Tag set must be URL-encoded first.
string
No
x-cos-forbid-overwrite
For buckets with versioning disabled, specifies whether to forbid overwriting objects with the same name during upload operations.
When the x-cos-forbid-overwrite header is not carried or is specified as false, the Object with the same name is overwritten by default.
When x-cos-forbid-overwrite is specified as true, it indicates that overwriting the Object with the same name is forbidden.
Note:
When versioning for a bucket is enabled, the x-cos-forbid-overwrite setting is ineffective, meaning overwriting objects with the same name is allowed.
string
No
Headers Related to Access Control List (ACL)
You can set the access permissions for an object during upload by specifying the following request headers:
Name
Description
Type
Required
x-cos-acl
Defines the Access Control List (ACL) property of an object. For the enumeration values, see the preset ACL section for objects in the ACL Overview document, such as default, private, public-read, and so on. The default value is default.
Note:
If you do not need to control object ACL, set it to default or leave it unset. In this case, bucket permissions are inherited by default.
Enum
No
x-cos-grant-read
Grants the grantee the permission to read the object. The format is id="[OwnerUin]", for example, id="100000000001". Multiple grantees can be separated by commas (,), for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grants the grantee the permission to read the Access Control List (ACL) of the object. The format is id="[OwnerUin]", for example, id="100000000001". Multiple grantees can be separated by commas (,), for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grants the grantee the permission to write to the Access Control List (ACL) of the object. The format is id="[OwnerUin]", for example, id="100000000001". Multiple grantees can be separated by commas (,), for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grants the grantee full control permissions over the object. The format is id="[OwnerUin]", for example, id="100000000001". Multiple grantees can be separated by commas (,), for example, id="100000000001",id="100000000002".
string
No
SSE-related headers
SSE can be used during object upload. For details, see Server-side encryption headers.

Request Body

This API has no request body.

Response

Response Headers

In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.
SSE-related headers
If SSE is used during object upload, this API returns headers used specifically for SSE. For details, see Server-Side Encryption Custom Header.

Response Body

Upon a successful request, application/xml data is returned, which contains the multipart upload initialization information.
<InitiateMultipartUploadResult>
       <Bucket>string</Bucket>
       <Key>string</Key>
       <UploadId>string</UploadId>
</InitiateMultipartUploadResult>
The detailed node descriptions are as follows:
Node Name (Keyword)
Parent Node
Description
Type
InitiateMultipartUploadResult
None
Saves all information of the Initiate Multipart Upload result.
Container
Container node InitiateMultipartUploadResult:
Node Name (Keyword)
Parent Node
Description
Type
Bucket
InitiateMultipartUploadResult
Target bucket
string
Key
InitiateMultipartUploadResult
Target Object Key
string
UploadId
InitiateMultipartUploadResult
The UploadId used in subsequent Upload Part operations
string

Error Codes

This API follows unified error responses and error codes. For details, see Error Codes.

Practical Case

Example One: Simple Case

Request

POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:01 GMT
Content-Type: video/mp4
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1585130821;1585138021&q-key-time=1585130821;1585138021&q-header-list=content-length;content-type;date;host&q-url-param-list=uploads&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Length: 230
Connection: close
Date: Wed, 25 Mar 2020 10:07:01 GMT
Server: tencent-cos
x-cos-request-id: NWU3YjJkNDVfNDliNTJhMDlfYzZhMl8yOTVj****

<InitiateMultipartUploadResult>
            <Bucket>examplebucket-1250000000</Bucket>
            <Key>exampleobject</Key>
            <UploadId>1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361</UploadId>
</InitiateMultipartUploadResult>

Example Two: Specifying Metadata and ACL Using Request Headers

Request

POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 28 May 2020 08:35:34 GMT
Content-Type: video/mp4
Cache-Control: max-age=86400
Content-Disposition: attachment; filename=example.jpg
x-cos-meta-example-field: example-value
x-cos-acl: public-read
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590654934;1590662134&q-key-time=1590654934;1590662134&q-header-list=cache-control;content-disposition;content-length;content-type;date;host;x-cos-acl;x-cos-meta-example-field&q-url-param-list=uploads&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 230
Connection: close
Date: Thu, 28 May 2020 08:35:34 GMT
Server: tencent-cos
x-cos-request-id: NWVjZjc3ZDZfOThjMjJhMDlfMjg5N18zNWYy****

<InitiateMultipartUploadResult>
            <Bucket>examplebucket-1250000000</Bucket>
            <Key>exampleobject</Key>
            <UploadId>1590654934dfb1343b4323b711afc22569c18af51596d4f2e40faf392fe1bb469c5b77115f</UploadId>
</InitiateMultipartUploadResult>

Example Three: Using Server-Side Encryption SSE-COS

Request

POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 28 May 2020 08:43:58 GMT
Content-Type: video/mp4
x-cos-server-side-encryption: AES256
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590655438;1590662638&q-key-time=1590655438;1590662638&q-header-list=content-length;content-type;date;host;x-cos-server-side-encryption&q-url-param-list=uploads&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 230
Connection: close
Date: Thu, 28 May 2020 08:43:58 GMT
Server: tencent-cos
x-cos-request-id: NWVjZjc5Y2VfZjhjODBiMDlfMjIyOGFfMzYxYWVm****
x-cos-server-side-encryption: AES256

<InitiateMultipartUploadResult>
            <Bucket>examplebucket-1250000000</Bucket>
            <Key>exampleobject</Key>
            <UploadId>15906554384f160dd0a272ebb6fbcdb0ffbb61adb2b46fa6b9f2ffabcfb2940b8f72277952</UploadId>
</InitiateMultipartUploadResult>

Example Four: Using Server-Side Encryption SSE-KMS

Request

POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 28 May 2020 08:44:19 GMT
Content-Type: video/mp4
x-cos-server-side-encryption: cos/kms
x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
x-cos-server-side-encryption-context: eyJhdXRob3IiOiJmeXNudGlhbiIsImNvbXBhbnkiOiJUZW5jZW50In0=
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590655459;1590662659&q-key-time=1590655459;1590662659&q-header-list=content-length;content-type;date;host;x-cos-server-side-encryption;x-cos-server-side-encryption-context;x-cos-server-side-encryption-cos-kms-key-id&q-url-param-list=uploads&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 230
Connection: close
Date: Thu, 28 May 2020 08:44:20 GMT
Server: tencent-cos
x-cos-request-id: NWVjZjc5ZTNfMmZiOTJhMDlfMzJlNDJfMjkzNGJi****
x-cos-server-side-encryption: cos/kms
x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****

<InitiateMultipartUploadResult>
            <Bucket>examplebucket-1250000000</Bucket>
            <Key>exampleobject</Key>
            <UploadId>15906554607990121702e8e4b706eb0f12b8568a3f3b0b76b884e4df676ed50291f0b17131</UploadId>
</InitiateMultipartUploadResult>

Example Five: Using Server-Side Encryption SSE-C

Request

POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 28 May 2020 08:44:41 GMT
Content-Type: application/xml
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590655481;1590662681&q-key-time=1590655481;1590662681&q-header-list=content-length;content-type;date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=uploads&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 230
Connection: close
Date: Thu, 28 May 2020 08:44:41 GMT
Server: tencent-cos
x-cos-request-id: NWVjZjc5ZjlfOGJjOTJhMDlfNzJmYV8xOTcy****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==

<InitiateMultipartUploadResult>
            <Bucket>examplebucket-1250000000</Bucket>
            <Key>exampleobject</Key>
            <UploadId>15906554815fb0c8bda2edae20d895ad7452e949bf51541b31ca14a029fb6f1617f10ca186</UploadId>
</InitiateMultipartUploadResult>
中国站 - English