Initiate Multipart Upload

Overview
This API is used to initialize a multipart upload. After a successful operation, UploadId will be returned, which can be used in subsequent Upload Part requests.
Note: 
Only the root account or sub-accounts granted the permission of the Initiate Multipart Upload API can call this API.
﻿
Request
Sample request
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, where <BucketName-APPID> is the is the bucket name followed by the APPID, such as examplebucket-1250000000 (see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions), and <Region> is a COS region (see Regions and Access Endpoints).
Authorization: Auth String (See Request Signature for details.)
Request parameters
This API has no request parameter.
Request headers
In addition to common request headers, this API also supports the following request headers. For more information about common request headers, please see Common Request Headers.
Header
Description
Type
Required
Cache-Control
Cache directives as defined in RFC 2616. It will be stored as object metadata.
string
No
Content-Disposition
Filename defined in RFC 2616. It will be stored as object metadata.
string
No
Content-Encoding
Encoding format as defined in RFC 2616. It will be stored as object metadata.
string
No
Content-Type
HTTP request content type (MIME) as defined in RFC 2616. This header describes the content type of the object to be uploaded and will be stored as object metadata.
Example: text/html, image/jpeg
string
Yes
Expires
The cache expiration time as defined in RFC 2616. It will be stored as object metadata.
string
No
x-cos-meta-*
Contains user-defined metadata and header suffixes. It will be stored as object metadata. Maximum size: 2 KB. 
Note: User-defined metadata can contain underscores (_), whereas the header suffixes of user-defined metadata can only contain minus signs (−) but not underscores.
string
No
x-cos-storage-class
Object storage class. For the enumerated values, such as STANDARD (default), INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview.
Enum
No
x-cos-tagging
A set of up to 10 object tags (for example, Key1=Value1&Key2=Value2). Tag key and tag value in the set must be URL-encoded.
string
No
x-cos-forbid-overwrite
For a bucket which has never enabled versioning, you may use it to specify whether to prohibit overwriting the object with the same name when uploading the object:
When the x-cos-forbid-overwrite header is not specified or specified as false, the object with the same name will be overwritten by default;
When the x-cos-forbid-overwrite is specified as true, overwriting the object with the same name will be prohibited.    
Note：
For a bucket which has enabled versioning or suspended versioning, the x-cos-forbid-overwrite request header is invalid,  which means overwriting objects with the same name is allowed whether the x-cos-forbid-overwrite request header is specified as true or false.          
string
Not required
ACL-related headers
You can configure an access control list (ACL) for the object by specifying the following request headers during the upload:
Header
Description
Type
Required
x-cos-acl
Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default. 
Note: If you do not need to set an ACL for the object, set this parameter to default or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
Enum
No
x-cos-grant-read
Grants a user read permission for an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grants a user read permission for the ACL of an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grants a user write permission for the ACL of an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grants a user full permission to operate on an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
SSE-related headers
Server-side encryption can be used during object upload. For more information, see Server-side encryption headers.
Request body
This API does not have a request body.
Response
Response headers
In addition to common response headers, this API also returns the following response headers. For more information about common response headers, please see Common Response Headers.
SSE-related headers
If server-side encryption is used during object upload, this API will return headers used specifically for server-side encryption. For more information, please see Server-Side Encryption Headers.
Response body
application/xml data that contains the multipart upload initialization information will be returned for a successful request.
<InitiateMultipartUploadResult>
       <Bucket>string</Bucket>
       <Key>string</Key>
       <UploadId>string</UploadId>
</InitiateMultipartUploadResult>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Type
InitiateMultipartUploadResult
None
Stores the result of Initiate Multipart Upload
Container
Content of `InitiateMultipartUploadResult:
Node Name (Keyword)
Parent Node
Description
Type
Bucket
InitiateMultipartUploadResult
Destination bucket
string
Key
InitiateMultipartUploadResult
Destination object key
string
UploadId
InitiateMultipartUploadResult
UploadId that can be used in subsequent Upload Part requests
string
Error codes
This API returns common error responses and error codes. For more information, see Error Codes.
Examples
Example 1: simple use 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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=38c5a4b181067206cdbdf65f6a4d662b2291****
Connection: close
Response
HTTP/1.1 200 OK
Content-Type: application/xml
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 2: 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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=5465e9e05cd638e549f66457235d488bfb02****
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 3: 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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=24fccaa68a5eb5e0a9e959dfd9493e3a0671****
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 4: 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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=11ab592d5aba2e740be67f69dfa254631293****
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 5: 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: video/mp4
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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=abd12e9b8c4334a803b5ed8cc03c697904f8****
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>
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

tencent cloud

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Example 1: simple use case

Request

Response

Example 2: specifying metadata and ACL using request headers

Request

Response

Example 3: using server-side encryption SSE-COS

Request

Response

Example 4: using server-side encryption SSE-KMS

Request

Response

Example 5: using server-side encryption SSE-C

Request

Response

About Tencent Cloud

Help & Support

Resources

User Center

Header	Description	Type	Required
Cache-Control	Cache directives as defined in RFC 2616. It will be stored as object metadata.	string	No
Content-Disposition	Filename defined in RFC 2616. It will be stored as object metadata.	string	No
Content-Encoding	Encoding format as defined in RFC 2616. It will be stored as object metadata.	string	No
Content-Type	HTTP request content type (MIME) as defined in RFC 2616. This header describes the content type of the object to be uploaded and will be stored as object metadata. Example: `text/html`, `image/jpeg`	string	Yes
Expires	The cache expiration time as defined in RFC 2616. It will be stored as object metadata.	string	No
x-cos-meta-*	Contains user-defined metadata and header suffixes. It will be stored as object metadata. Maximum size: 2 KB. Note: User-defined metadata can contain underscores (_), whereas the header suffixes of user-defined metadata can only contain minus signs (−) but not underscores.	string	No
x-cos-storage-class	Object storage class. For the enumerated values, such as `STANDARD` (default), `INTELLIGENT_TIERING`, `STANDARD_IA`, `ARCHIVE`, and `DEEP_ARCHIVE`, please see Storage Class Overview.	Enum	No
x-cos-tagging	A set of up to 10 object tags (for example, `Key1=Value1&Key2=Value2`). Tag key and tag value in the set must be URL-encoded.	string	No
x-cos-forbid-overwrite	For a bucket which has never enabled versioning, you may use it to specify whether to prohibit overwriting the object with the same name when uploading the object: When the x-cos-forbid-overwrite header is not specified or specified as false, the object with the same name will be overwritten by default; When the x-cos-forbid-overwrite is specified as true, overwriting the object with the same name will be prohibited. Note： For a bucket which has enabled versioning or suspended versioning, the x-cos-forbid-overwrite request header is invalid, which means overwriting objects with the same name is allowed whether the x-cos-forbid-overwrite request header is specified as true or false.	string	Not required

Node Name (Keyword)	Parent Node	Description	Type
InitiateMultipartUploadResult	None	Stores the result of `Initiate Multipart Upload`	Container

tencent cloud

Sign Up

Log in

Compute

Microservice

Data Migration

Database SaaS Tool

Data Security

Application Security

Big Data

Voice Technology

Internet of Things

Stream Services

Cloud Real-time Rendering

Cloud Resource Management

More

Edge Computing

Serverless

Relational Database

Networking

Business Security

Domains & Websites

Face Recognition

AI Platform Service

Middleware

Media On-Demand

Game Services

Management and Audit Tools

Container

Essential Storage Service

Enterprise Distributed DBMS

CDN and Acceleration

Security Services

Enterprise Applications

Image Creation

Natural Language Processing

Communication

Media Process Services

Education Sevices

Developer Tools

Distributed cloud

Data Process and Analysis

NoSQL Database

Network Security

Cloud Security

Office Collaboration

Tencent Big Model

Optical Character Recognition

Interactive Video Services

Media SDK

Medical Services

Monitor and Operation

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Example 1: simple use case

Request

Response

Example 2: specifying metadata and ACL using request headers

Request

Response

Example 3: using server-side encryption SSE-COS

Request

Response

Example 4: using server-side encryption SSE-KMS

Request

Response

Example 5: using server-side encryption SSE-C

Request

Response

About Tencent Cloud

Help & Support