This API is used to initialize a multipart upload. A successful request to this API will return an UploadId that is used in the subsequent Upload Part requests.
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 StringAuthorization: Auth String (see Request Signature for more information)
This API does not use any request parameter.
In addition to common request headers, this API also supports the following request headers. For more information on common request headers, see Common Request Headers.
| Name | Description | Type | Required |
|---|---|---|---|
| Cache-Control | Cache directives as defined in RFC 2616, which are stored as part of object metadata | string | No |
| Content-Disposition | File name as defined in RFC 2616, which is stored as part of object metadata | string | No |
| Content-Encoding | Encoding format as defined in RFC 2616, which is stored as part of object metadata | string | No |
| Content-Type | HTTP request content type (MIME) as defined in RFC 2616 of the object to upload, and stored as part of object metadata Example: text/html or image/jpeg |
string | Yes |
| Expires | The cache expiration time as defined in RFC 2616, which is stored as part of object metadata | string | No |
| x-cos-meta-* | Includes custom metadata and its header suffix, which are stored as part of object metadata. Maximum size: 2 KB. Note: custom metadata can contain underscores (_), whereas its header suffix can only contain minus signs (-). |
string | No |
| x-cos-storage-class | Specifies the storage class of the object. For enumerated values, see Storage Class Overview, such as INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE and DEEP_ARCHIVE. Default value: STANDARD | Enum | No |
| x-cos-tagging | Specifies a tag set that can contain up to 10 object tags, e.g., "Key1=Value1&Key2=Value2", where the "Key" and "Value" must be URL-encoded first | string | No |
ACL-related headers
You can configure object access permissions when uploading an object using the following request headers:
| Name | Description | Type | Required |
|---|---|---|---|
| x-cos-acl | Defines the access control list (ACL) attributes of the object. For enumerated values such as default, private, and public-read, see the Preset ACL section in ACL Overview.Note: If you do not need an object ACL, set this parameter to default (inherit bucket permissions), or leave it empty. |
Enum | No |
| x-cos-grant-read | Allows grantee to read the object; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
String | No |
| x-cos-grant-read-acp | Allows grantee to read the object ACL; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
String | No |
| x-cos-grant-write-acp | Allows grantee to write the object ACL; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
String | No |
| x-cos-grant-full-control | Allows grantee full control over the object; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" |
String | No |
Headers related to server-side encryption (SSE)
To use SSE encryption for uploading objects, see Server-side encryption headers.
This API does not have a request body.
In addition to common response headers, this API also returns the following response headers. For more information on common response headers, see Common Response Headers.
Headers related to server-side encryption (SSE)
If you uploaded the object using SSE encryption, this API will return SSE headers. For more information, see Server-side encryption headers.
A successful request returns application/xml data, including the initialization of multipart upload.
<InitiateMultipartUploadResult>
<Bucket>string</Bucket>
<Key>string</Key>
<UploadId>string</UploadId>
</InitiateMultipartUploadResult>The detailed nodes are described as follows:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| InitiateMultipartUploadResult | None | Contains all results of the Initiate Multipart Upload action | Container |
Content of the Container node InitiateMultipartUploadResult:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| Bucket | InitiateMultipartUploadResult | Destination bucket | string |
| Key | InitiateMultipartUploadResult | Destination object key | string |
| UploadId | InitiateMultipartUploadResult | The UploadId used in subsequent Upload Part requests | string |
This API uses standardized error responses and error codes. For more information, see Error Codes .
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: closeHTTP/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>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: closeHTTP/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>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: closeHTTP/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>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: closeHTTP/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>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: closeHTTP/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?