Cloud Object Storage POST Object-Object APIs-APIs-Tencent Cloud

Feature Overview
This API is used to upload an object within 5 GB to a bucket using an HTML form. To call this API, you need to have permission to write to the bucket.
Note
The POST Object API does not use the unified request signature for COS object storage but has its own signature requirements. Please refer to Signature Protection and the descriptions of related fields in this document.
If you upload an object whose name is the same as another object that is already stored in the bucket with versioning disabled, the old object will be overwritten and the response will be returned normally as specified upon successful upload.
When uploading an image, please refer to the PUT Object API and follow the code examples for data population.
﻿
Versioning
For a versioning-enabled bucket, COS will automatically generate a unique version ID for the concatenated object, and the ID will be returned in the x-cos-version-id response header.
For a versioning-suspended bucket, COS will always use null as the version ID of the object and will not return the x-cos-version-id response header.
Requests
Sample Request
POST / HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: multipart/form-data; boundary=Multipart Boundary
Content-Length: Content Length
﻿
﻿
﻿
[Multipart Form Data]
Note
 Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, where <BucketName-APPID> is the bucket name with the APPID suffix, such as examplebucket-1250000000. Refer to Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Convention documentation; <Region> is the available region for COS, refer to Regions and Access Domain Names documentation.
Request form
This interface request body uses multipart/form-data encoding. When sending a request through the <form> element in an HTML page, set the enctype attribute of the <form> element to multipart/form-data. Then, use HTML form elements (such as <input>, <select>, etc.) to add the required form fields.
Form fields
Name
Description
Local Disk Types
Required
key
Object key. If you use the ${filename} wildcard in the object key, the wildcard will be replaced with the name of the object uploaded (see Example 7).
string
Required
Cache-Control
Cache directives as defined in RFC 2616. It will be stored as object metadata.
string
Not required
Content-Disposition
Filename as defined in RFC 2616. It will be stored as object metadata.
string
Not required
Content-Encoding
Encoding format as defined in RFC 2616. It will be stored as object metadata.
string
Not required
Content-Type
HTTP content type (MIME) as defined in RFC 2616. It will be stored as object metadata.
Note: When uploading files via a web form, the browser automatically includes the MIME type of the specified file in the request. However, COS does not use the MIME type provided by the browser. You need to explicitly specify the Content-Type form field as the object's content type.
string
Not required
Expires
The cache expiration time as defined in RFC 2616, which is saved as part of the object metadata.
string
Not required
success_action_redirect
Upon successful upload, the target URL address for redirection. If set, an HTTP status code of 303 (Redirect) and a Location response header will be returned. The value of the Location response header will be the URL address specified in this field, along with bucket, key, and etag parameters. For related examples, please refer to Case 8 in this document.
string
Not required
success_action_status
HTTP status code returned upon successful upload. Valid values are 200, 201, or 204, with the default being 204. If the success_action_redirect field is specified, this field will be ignored. For related examples, please refer to Case 9 in this document.
number
Not required
x-cos-meta-*
Including user-defined metadata header suffix and user-defined metadata information, which will be stored as object metadata with a size limit of 2KB.
Note: User-defined metadata information supports underscores (_), but user-defined metadata header suffixes do not support underscores and only support hyphens (-).
string
Not required
x-cos-storage-class
Object storage class. For enumeration values, please refer to the Storage Types document, such as MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE. Default value: STANDARD.
Enum
Not required
x-cos-traffic-limit
The rate limit for traffic control applied to this upload, which must be a numeric value with the default unit being bit/s. The rate limit range is 819,200 - 838,860,800, i.e., 800 Kb/s - 800 Mb/s. If the value exceeds this range, a 400 error will be returned.
integer
Not required
Content-MD5
MD5 checksum of the Base64-encoded file content. It is used for integrity check, i.e., whether the file content has changed during the upload.
string
Not required
file
File content. When uploading the file via a form, the browser will automatically configure the field in proper format
Note: The file field must be placed at the end of the entire form.
file
Required
ACL-related form fields
You can configure access permissions for the object by specifying the following form fields during upload:
Name                                  
Description
Local Disk Types
Required
acl
Defines the Access Control List (ACL) attribute for the object. For enumeration values, refer to the Preset ACL section in the ACL Overview document, such as default, private, public-read, etc. The default value is 'default'.
Note: If you do not require object ACL control, set it to default or leave this option unset, and the object will inherit the bucket permissions by default.
Enum
Not required
x-cos-grant-read
Grant the permission to read objects to the authorized party, with the format id="[OwnerUin]", for example, id="100000000001". Multiple authorized parties can be separated by a comma (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-read-acp
Grant the permission to read the object's Access Control List (ACL) to the authorized party, with the format id="[OwnerUin]", for example, id="100000000001". Multiple authorized parties can be separated by a comma (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-write-acp
Grant the permission to write the object's Access Control List (ACL) to the authorized party, with the format id="[OwnerUin]", for example, id="100000000001". Multiple authorized parties can be separated by a comma (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-full-control
Grant all permissions to the authorized party to operate the object, with the format id="[OwnerUin]", for example, id="100000000001". Multiple authorized parties can be separated by a comma (,), for example, id="100000000001",id="100000000002".
string
Not required
SSE-related form fields
You can use server-side encryption by specifying the following form fields during upload:
Name
Description
Local Disk Types
Required
x-cos-server-side-encryption
Server-side encryption algorithm. AES256 and cos/kms are supported.
string
Required if SSE-COS or SSE-KMS is used
x-cos-server-side-encryption-customer-algorithm
Server-side encryption algorithm. AES256 is supported.
string
Required if SSE-C is used
x-cos-server-side-encryption-cos-kms-key-id
When x-cos-server-side-encryption value is cos/kms, it is used to specify the user master key of KMS. If not specified, CMK created by COS is used by default. For more details, please refer to SSE-KMS Encryption
string
Not required
x-cos-server-side-encryption-context
When x-cos-server-side-encryption value is cos/kms, this parameter specifies the encryption context, and the value is a JSON key-value pair expressed in Base64 encoding.
For example, eyJhIjoiYXNkZmEiLCJiIjoiMTIzMzIxIn0=
string
Not required
x-cos-server-side-encryption-customer-key
Base64-encoded server-side encryption key
Example: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
string
Required if SSE-C is used
x-cos-server-side-encryption-customer-key-MD5
The MD5 hash value of the server-side encryption key, encoded in Base64.
Example: U5L61r7jcwdNvT7frmUG8g==
string
Required if SSE-C is used
Signature protection
This API requires signature-related fields to be carried in the request. COS authenticates the messages carried, and if the authentication is passed, COS executes the request. If not, COS returns an error message and discards the request.
You can generate a signature as follows:
1. Preparation
Log in to the CAM Console and get your project's SecretId and SecretKey on the API Key Management page.
2. Generating KeyTime
a. Obtain the Unix timestamp (StartTimestamp) corresponding to the current time. The Unix timestamp is the total number of seconds elapsed since 00:00:00 UTC (Coordinated Universal Time, or GMT Greenwich Mean Time) on January 1, 1970 (Beijing Time: 08:00:00 on January 1, 1970).
b. Calculate the Unix timestamp (EndTimestamp) for the signature expiration time based on the above timestamp and the desired signature validity duration.
c. Concatenate the signature validity period in the format StartTimestamp;EndTimestamp, which is the KeyTime.
3. Constructing a "Policy"
A policy is a text in JSON format. A typical policy is as follows:
{
    "expiration": "2019-08-30T09:38:12.414Z",
    "conditions": [
        { "acl": "default" },
        { "bucket": "examplebucket-1250000000" },
        [ "starts-with", "$key", "folder/subfolder/" ],
        [ "starts-with", "$Content-Type", "image/" ],
        [ "starts-with", "$success_action_redirect", "https://my.website/" ],
        [ "eq", "$x-cos-server-side-encryption", "AES256" ],
        { "q-sign-algorithm": "sha1" },
        { "q-ak": "************************************" },
        { "q-sign-time": "1567150692;1567157892" }
    ]
}
In the description:
expiration: The policy's expiration time, which is a string in ISO 8601 format.
conditions: An array of conditions for the policy. The conditions are described below.
Local Disk Types
Description
Exact Match
Use {" key ":" value "} or [" eq "," $ key "," value "] to express, where key is a specified form field and value is a specified value
Prefix Match
Use [ "starts-with", "$key", "value" ] to express, where key is a specified form field and value is a specified prefix that can be empty
Range Match
Only applies to [" content-length-range ", minNum, maxNum], used to limit the file length to be within minNum and maxNum
Form fields that can be limited are as follows:
Field
Description
Matching Method       
Required
acl
ACL attribute of the object
Exact/Prefix
Not required
bucket
Bucket for upload
Exact
Not required
key
Object key. If you use the ${filename} wildcard in the object key during upload, the object key will be processed to the final object key before the policy is verified. Therefore, you should use prefix match in the policy and ${filename} should not appear.
Exact/Prefix
Not required
content-length-range
Range of the file length
Description
Not required
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires
Headers defined in RFC 2616, which will be returned as response headers when the object is downloaded.
Exact/Prefix
Not required
success_action_redirect
Redirection target URL when the upload succeeds
Exact/Prefix
Not required
success_action_status
HTTP status code returned when the upload succeeds
Exact
Not required
x-cos-meta-*
User-defined metadata headers
Exact/Prefix
Not required
x-cos-*
Other COS-related form fields described in this document, such as ACL- or SSE-related fields
Exact
Not required
q-sign-algorithm
Signature hash algorithm. Fixed at sha1
Exact
Required
q-ak
SecretId mentioned above
Exact
Required
q-sign-time
KeyTime generated above
Exact
Required
Note
Fields other than buckets defined in “Policy” must appear in form fields. For example, if you specify {" acl ":" default "}, acl must appear in the form with the default value.
For security reasons, we strongly recommend you specify all form fields that can be specified.
4. Generating SignKey
Using HMAC-SHA1 with SecretKey as the key and KeyTime as the message, calculate the message digest (hash value in hexadecimal lowercase form), which is the SignKey. For example: 39acc8c9f34ba5b19bce4e965b370cd3f62d2fba.
5. Generating StringToSign
Calculate the message digest (hash value in hexadecimal lowercase form) of the constructed policy text using SHA1, which is the StringToSign. For example: d5d903b8360468bc81c1311f134989bc8c8b5b89.
6. Generating Signature
Using HMAC-SHA1 with SignKey as the key (string form, not raw binary) and StringToSign as the message (string form, not raw binary), calculate the message digest (hash value in hexadecimal lowercase form), which is the Signature. For example: 7758dc9a832e9d301dca704cacbf9d9f8172fdef.
7. Attaching the signature to the form
Attach the policy and signature-related information above to the form as described in the following table:
Name
Description
Local Disk Types
Required
x-cos-security-token
Security token when a temporary security token is used. For more information, please see Temporary security credentials.
string
No, when using temporary
When using a key, this form item is required.
policy
Base64-encoded policy
string
Required
q-sign-algorithm
Signature hash algorithm. Fixed at sha1
string
Required
q-ak
SecretId mentioned above
string
Required
q-key-time
KeyTime generated above
string
Required
q-signature
Signature generated above
string
Required
Note
The signature form field must be placed before the file form field.
Signature protection use cases
Preparation
Obtain your APPID, SecretId, and SecretKey on the API Key Management page in the CAM Console. Below is an example:
APPID
SecretId
SecretKey
1250000000
************************************
BQYIM75p8x0iWVFSIgqEKwFprpRSVHlz
Constructing a policy
{
    "expiration": "2019-08-30T09:38:12.414Z",
    "conditions": [
        { "acl": "default" },
        { "bucket": "examplebucket-1250000000" },
        [ "starts-with", "$key", "folder/subfolder/" ],
        [ "starts-with", "$Content-Type", "image/" ],
        [ "starts-with", "$success_action_redirect", "https://my.website/" ],
        [ "eq", "$x-cos-server-side-encryption", "AES256" ],
        { "q-sign-algorithm": "sha1" },
        { "q-ak": "************************************" },
        { "q-sign-time": "1567150692;1567157892" }
    ]
}
Intermediate variables
KeyTime = 1567150692;1567157892
SignKey = 39acc8c9f34ba5b19bce4e965b370cd3f62d2fba
StringToSign = d5d903b8360468bc81c1311f134989bc8c8b5b89
Signature = 7758dc9a832e9d301dca704cacbf9d9f8172fdef
Signature form fields
policy = ewogICAgImV4cGlyYXRpb24iOiAiMjAxOS0wOC0zMFQwOTozODoxMi40MTRaIiwKICAgICJjb25kaXRpb25zIjogWwogICAgICAgIHsgImFjbCI6ICJkZWZhdWx0IiB9LAogICAgICAgIHsgImJ1Y2tldCI6ICJleGFtcGxlYnVja2V0LTEyNTAwMDAwMDAiIH0sCiAgICAgICAgWyAic3RhcnRzLXdpdGgiLCAiJGtleSIsICJmb2xkZXIvc3ViZm9sZGVyLyIgXSwKICAgICAgICBbICJzdGFydHMtd2l0aCIsICIkQ29udGVudC1UeXBlIiwgImltYWdlLyIgXSwKICAgICAgICBbICJzdGFydHMtd2l0aCIsICIkc3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiLCAiaHR0cHM6Ly9teS53ZWJzaXRlLyIgXSwKICAgICAgICBbICJlcSIsICIkeC1jb3Mtc2VydmVyLXNpZGUtZW5jcnlwdGlvbiIsICJBRVMyNTYiIF0sCiAgICAgICAgeyAicS1zaWduLWFsZ29yaXRobSI6ICJzaGExIiB9LAogICAgICAgIHsgInEtYWsiOiAiQUtJRFFqejNsdG9tcFZqQm5pNUxpdGtXSEZsRnB3a245VTVxIiB9LAogICAgICAgIHsgInEtc2lnbi10aW1lIjogIjE1NjcxNTA2OTI7MTU2NzE1Nzg5MiIgfQogICAgXQp9
q-sign-algorithm = sha1
q-ak = ************************************
q-key-time = 1567150692;1567157892
q-signature = 7758dc9a832e9d301dca704cacbf9d9f8172fdef
Response
Response Header
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.
Name
Description
Local Disk Types
Location
When using the success_action_redirect form field, the value of this response header is the URL specified by success_action_redirect, with the addition of bucket, key, and etag parameters. For a related example, please refer to Case 8 in this document.
When the success_action_redirect form field is not used, the value of this response header is the complete object access URL. For a related example, please refer to Case 1 in this document.
string
Versioning-Related Headers
If the object is uploaded to a versioning-enabled bucket, the following response headers will be returned:
Name
Description
Local Disk Types
x-cos-version-id
Version ID of the object
string
Headers related to server-side encryption (SSE)
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
The response body of this API is empty.
Error Codes
This API returns common error responses and error codes. For more information, see Error Codes.
Examples
Example 1: simple use case (with versioning disabled)
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:34 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Length: 1119
Connection: close
﻿
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJxLXNpZ24tYWxnb3JpdGhtIjoic2hhMSJ9LHsicS1hayI6IkFLSUQ4QTBmQlZ0WUZyTm0wMm9ZMWcxSlFRRjBjM0pPNk5FdSJ9LHsicS1zaWduLXRpbWUiOiIxNTY3MDY0Mzc0OzE1NjcwNzE1NzQifV0sImV4cGlyYXRpb24iOiIyMDE5LTA4LTI5VDA5OjM5OjM0LjQ3MVoifQ==
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-key-time"
﻿
1567064374;1567071574
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-signature"
﻿
74ba120129a13d8f0e19479fbdc01bca3bca****
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryZBPbaoYE2gqeB21N--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:39:34 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxMzZfMmViMDJhMDlfY2NjOF84NGQz****
Sample 2: Specifying metadata and ACL using form fields
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:34 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Length: 2146
Connection: close
﻿
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="acl"
﻿
public-read
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="Cache-Control"
﻿
max-age=86400
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="Content-Disposition"
﻿
attachment; filename=example.jpg
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="Content-Type"
﻿
image/jpeg
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="x-cos-meta-example-field"
﻿
example-value
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="Content-MD5"
﻿
7o3pGNBWQBRbGPcPTDqmAg==
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJhY2wiOiJwdWJsaWMtcmVhZCJ9LHsiYnVja2V0IjoiZXhhbXBsZWJ1Y2tldC0xMjUyMjQ2NTU1In0seyJrZXkiOiJleGFtcGxlb2JqZWN0In0sWyJlcSIsIiRDb250ZW50LURpc3Bvc2l0aW9uIiwiYXR0YWNobWVudDsgZmlsZW5hbWU9ZXhhbXBsZS5qcGciXSxbInN0YXJ0cy13aXRoIiwiJENvbnRlbnQtVHlwZSIsImltYWdlLyJdLFsiZXEiLCIkeC1jb3MtbWV0YS1leGFtcGxlLWZpZWxkIiwiZXhhbXBsZS12YWx1ZSJdLHsicS1zaWduLWFsZ29yaXRobSI6InNoYTEifSx7InEtYWsiOiJBS0lEOEEwZkJWdFlGck5tMDJvWTFnMUpRUUYwYzNKTzZORXUifSx7InEtc2lnbi10aW1lIjoiMTU2NzA2NDM3NDsxNTY3MDcxNTc0In1dLCJleHBpcmF0aW9uIjoiMjAxOS0wOC0yOVQwOTozOTozNC45MzdaIn0=
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="q-key-time"
﻿
1567064374;1567071574
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="q-signature"
﻿
228a89b5f7b8fce7fdfa4a3b36cfb5a5eafb****
------WebKitFormBoundary9JtEhEGHSdx8Patg
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundary9JtEhEGHSdx8Patg--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:39:35 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxMzdfM2NhZjJhMDlfMTQzYV84Nzhh****
Sample 3: using server-side encryption SSE-COS
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:35 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Length: 1296
Connection: close
﻿
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="x-cos-server-side-encryption"
﻿
AES256
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJ4LWNvcy1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjoiQUVTMjU2In0seyJxLXNpZ24tYWxnb3JpdGhtIjoic2hhMSJ9LHsicS1hayI6IkFLSUQ4QTBmQlZ0WUZyTm0wMm9ZMWcxSlFRRjBjM0pPNk5FdSJ9LHsicS1zaWduLXRpbWUiOiIxNTY3MDY0Mzc1OzE1NjcwNzE1NzUifV0sImV4cGlyYXRpb24iOiIyMDE5LTA4LTI5VDA5OjM5OjM1LjUyN1oifQ==
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="q-key-time"
﻿
1567064375;1567071575
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="q-signature"
﻿
65f3f8864bb1b271e1235d1ec7d1cb508ffa****
------WebKitFormBoundaryBVaHvBJQJnQrAxKY
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryBVaHvBJQJnQrAxKY--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:39:35 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxMzdfMTljMDJhMDlfNTg4ZF84Njgx****
x-cos-server-side-encryption: AES256
Sample 4: using server-side encryption SSE-C
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:36 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Length: 1667
Connection: close
﻿
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="x-cos-server-side-encryption-customer-algorithm"
﻿
AES256
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="x-cos-server-side-encryption-customer-key"
﻿
MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="x-cos-server-side-encryption-customer-key-MD5"
﻿
U5L61r7jcwdNvT7frmUG8g==
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJ4LWNvcy1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uLWN1c3RvbWVyLWFsZ29yaXRobSI6IkFFUzI1NiJ9LHsicS1zaWduLWFsZ29yaXRobSI6InNoYTEifSx7InEtYWsiOiJBS0lEOEEwZkJWdFlGck5tMDJvWTFnMUpRUUYwYzNKTzZORXUifSx7InEtc2lnbi10aW1lIjoiMTU2NzA2NDM3NjsxNTY3MDcxNTc2In1dLCJleHBpcmF0aW9uIjoiMjAxOS0wOC0yOVQwOTozOTozNi4wODdaIn0=
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="q-key-time"
﻿
1567064376;1567071576
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="q-signature"
﻿
0273a4b4ede39d0e5162758e145ea0c3e9ef****
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryYa6H7Gd4xuhlyfJb--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:39:36 GMT
ETag: "582d9105f71525f3c161984bc005efb5"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxMzhfMzdiMDJhMDlfNDA4YV84MzQx****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
Sample 5: versioning-enabled
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:40:07 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Length: 1119
Connection: close
﻿
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJxLXNpZ24tYWxnb3JpdGhtIjoic2hhMSJ9LHsicS1hayI6IkFLSUQ4QTBmQlZ0WUZyTm0wMm9ZMWcxSlFRRjBjM0pPNk5FdSJ9LHsicS1zaWduLXRpbWUiOiIxNTY3MDY0NDA3OzE1NjcwNzE2MDcifV0sImV4cGlyYXRpb24iOiIyMDE5LTA4LTI5VDA5OjQwOjA3LjQ4OFoifQ==
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="q-key-time"
﻿
1567064407;1567071607
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="q-signature"
﻿
699ad0ce7780eb559b75e88f77e95743d829****
------WebKitFormBoundaryJspR3QIUhGJLALwf
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryJspR3QIUhGJLALwf--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:40:07 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxNTdfNzFiNDBiMDlfMmE3ZmJfODQ1****
x-cos-version-id: MTg0NDUxNzcwMDkzMDE3NDQ0MDU
Sample 6: versioning-suspended
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:40:38 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Length: 1119
Connection: close
﻿
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJxLXNpZ24tYWxnb3JpdGhtIjoic2hhMSJ9LHsicS1hayI6IkFLSUQ4QTBmQlZ0WUZyTm0wMm9ZMWcxSlFRRjBjM0pPNk5FdSJ9LHsicS1zaWduLXRpbWUiOiIxNTY3MDY0NDM4OzE1NjcwNzE2MzgifV0sImV4cGlyYXRpb24iOiIyMDE5LTA4LTI5VDA5OjQwOjM4LjA5MloifQ==
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="q-key-time"
﻿
1567064438;1567071638
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="q-signature"
﻿
bb04222322bfb17f4d1f43833bbbac0a03aa****
------WebKitFormBoundaryX8hd2lxTMzIBk5Li
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryX8hd2lxTMzIBk5Li--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 07:40:38 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2NzgxNzZfMjFjOTBiMDlfMWY3YTFfNjY2****
Example 7: Object key (form field key) uses $ {filename} wildcard
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 12:35:07 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Length: 1188
Connection: close
﻿
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="key"
﻿
folder/subfolder/${filename}
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJmb2xkZXIvc3ViZm9sZGVyLyJdLHsicS1zaWduLWFsZ29yaXRobSI6InNoYTEifSx7InEtYWsiOiJBS0lEOEEwZkJWdFlGck5tMDJvWTFnMUpRUUYwYzNKTzZORXUifSx7InEtc2lnbi10aW1lIjoiMTU2NzA4MjEwNzsxNTY3MDg5MzA3In1dLCJleHBpcmF0aW9uIjoiMjAxOS0wOC0yOVQxNDozNTowNy44OTlaIn0=
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="q-key-time"
﻿
1567082107;1567089307
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="q-signature"
﻿
3cc37f8c81e36f57506efa02d0a3b6c9d551****
------WebKitFormBoundaryHrAMWZO4BNyT0rca
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryHrAMWZO4BNyT0rca--
﻿
Response
HTTP/1.1 204 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 12:35:08 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/folder/subfolder/photo.jpg
Server: tencent-cos
x-cos-request-id: NWQ2N2M2N2NfNWZhZjJhMDlfNmUzMV84OTg4****
Sample 8: Specifying the success_action_redirect form field
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 08:02:29 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Length: 1351
Connection: close
﻿
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="success_action_redirect"
﻿
https://my.website/upload_success.html
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbWyJzdGFydHMtd2l0aCIsIiRzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCIsImh0dHBzOi8vbXkud2Vic2l0ZS8iXSx7InEtc2lnbi1hbGdvcml0aG0iOiJzaGExIn0seyJxLWFrIjoiQUtJRDhBMGZCVnRZRnJObTAyb1kxZzFKUVFGMGMzSk82TkV1In0seyJxLXNpZ24tdGltZSI6IjE1NjcwNjU3NDk7MTU2NzA3Mjk0OSJ9XSwiZXhwaXJhdGlvbiI6IjIwMTktMDgtMjlUMTA6MDI6MjkuMjcyWiJ9
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="q-key-time"
﻿
1567065749;1567072949
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="q-signature"
﻿
c4a8ae7411687bc3d6ed2ac9b249e87a50b5****
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryJ0bRH1MwgMq5eu6H--
﻿
Response
HTTP/1.1 303 Redirect
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 08:02:29 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: https://my.website/upload_success.html?bucket=examplebucket-1250000000&key=exampleobject&etag=%22ee8de918d05640145b18f70f4c3aa602%22
Server: tencent-cos
x-cos-request-id: NWQ2Nzg2OTVfMTRiYjI0MDlfZGFkOV85MDA4****
Sample 9: Specifying the success_action_status form field
Requests
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 08:04:29 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Length: 1270
Connection: close
﻿
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="success_action_status"
﻿
200
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="policy"
﻿
eyJjb25kaXRpb25zIjpbeyJzdWNjZXNzX2FjdGlvbl9zdGF0dXMiOiIyMDAifSx7InEtc2lnbi1hbGdvcml0aG0iOiJzaGExIn0seyJxLWFrIjoiQUtJRDhBMGZCVnRZRnJObTAyb1kxZzFKUVFGMGMzSk82TkV1In0seyJxLXNpZ24tdGltZSI6IjE1NjcwNjU4Njk7MTU2NzA3MzA2OSJ9XSwiZXhwaXJhdGlvbiI6IjIwMTktMDgtMjlUMTA6MDQ6MjkuMzI3WiJ9
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="q-ak"
﻿
************************************
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="q-key-time"
﻿
1567065869;1567073069
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="q-signature"
﻿
e46285af04d4fb68e0624fdd0a525b6a07ab****
------WebKitFormBoundaryST9Mz8AGzCDphgJF
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
﻿
[Object Content]
------WebKitFormBoundaryST9Mz8AGzCDphgJF--
﻿
Response
HTTP/1.1 200 
Content-Length: 0
Connection: close
Date: Thu, 29 Aug 2019 08:04:29 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Location: http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
Server: tencent-cos
x-cos-request-id: NWQ2Nzg3MGRfZjhjODBiMDlfOGM3N184Nzdl****
﻿

Name	Description	Local Disk Types	Required
key	Object key. If you use the `${filename}` wildcard in the object key, the wildcard will be replaced with the name of the object uploaded (see Example 7).	string	Required
Cache-Control	Cache directives as defined in RFC 2616. It will be stored as object metadata.	string	Not required
Content-Disposition	Filename as defined in RFC 2616. It will be stored as object metadata.	string	Not required
Content-Encoding	Encoding format as defined in RFC 2616. It will be stored as object metadata.	string	Not required
Content-Type	HTTP content type (MIME) as defined in RFC 2616. It will be stored as object metadata. Note: When uploading files via a web form, the browser automatically includes the MIME type of the specified file in the request. However, COS does not use the MIME type provided by the browser. You need to explicitly specify the Content-Type form field as the object's content type.	string	Not required
Expires	The cache expiration time as defined in RFC 2616, which is saved as part of the object metadata.	string	Not required
success_action_redirect	Upon successful upload, the target URL address for redirection. If set, an HTTP status code of 303 (Redirect) and a Location response header will be returned. The value of the Location response header will be the URL address specified in this field, along with bucket, key, and etag parameters. For related examples, please refer to Case 8 in this document.	string	Not required
success_action_status	HTTP status code returned upon successful upload. Valid values are 200, 201, or 204, with the default being 204. If the success_action_redirect field is specified, this field will be ignored. For related examples, please refer to Case 9 in this document.	number	Not required
x-cos-meta-*	Including user-defined metadata header suffix and user-defined metadata information, which will be stored as object metadata with a size limit of 2KB. Note: User-defined metadata information supports underscores (_), but user-defined metadata header suffixes do not support underscores and only support hyphens (-).	string	Not required
x-cos-storage-class	Object storage class. For enumeration values, please refer to the Storage Types document, such as MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE. Default value: STANDARD.	Enum	Not required
x-cos-traffic-limit	The rate limit for traffic control applied to this upload, which must be a numeric value with the default unit being bit/s. The rate limit range is 819,200 - 838,860,800, i.e., 800 Kb/s - 800 Mb/s. If the value exceeds this range, a 400 error will be returned.	integer	Not required
Content-MD5	MD5 checksum of the Base64-encoded file content. It is used for integrity check, i.e., whether the file content has changed during the upload.	string	Not required
file	File content. When uploading the file via a form, the browser will automatically configure the field in proper format Note: The file field must be placed at the end of the entire form.	file	Required

Local Disk Types	Description
Exact Match	Use `{" key ":" value "}` or `[" eq "," $ key "," value "]` to express, where key is a specified form field and value is a specified value
Prefix Match	Use `[ "starts-with", "$key", "value" ]` to express, where key is a specified form field and value is a specified prefix that can be empty
Range Match	Only applies to `[" content-length-range ", minNum, maxNum]`, used to limit the file length to be within minNum and maxNum

Field	Description	Matching Method	Required
acl	ACL attribute of the object	Exact/Prefix	Not required
bucket	Bucket for upload	Exact	Not required
key	Object key. If you use the `${filename}` wildcard in the object key during upload, the object key will be processed to the final object key before the policy is verified. Therefore, you should use prefix match in the policy and `${filename}` should not appear.	Exact/Prefix	Not required
content-length-range	Range of the file length	Description	Not required
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires	Headers defined in RFC 2616, which will be returned as response headers when the object is downloaded.	Exact/Prefix	Not required
success_action_redirect	Redirection target URL when the upload succeeds	Exact/Prefix	Not required
success_action_status	HTTP status code returned when the upload succeeds	Exact	Not required
x-cos-meta-*	User-defined metadata headers	Exact/Prefix	Not required
x-cos-*	Other COS-related form fields described in this document, such as ACL- or SSE-related fields	Exact	Not required
q-sign-algorithm	Signature hash algorithm. Fixed at `sha1`	Exact	Required
q-ak	`SecretId` mentioned above	Exact	Required
q-sign-time	`KeyTime` generated above	Exact	Required

APPID	SecretId	SecretKey
1250000000	************************************	BQYIM75p8x0iWVFSIgqEKwFprpRSVHlz

POST Object

On this page:

Feature Overview

Versioning

Requests

Sample Request

Request form

Signature protection

1. Preparation

2. Generating KeyTime

3. Constructing a "Policy"

4. Generating SignKey

5. Generating StringToSign

6. Generating Signature

7. Attaching the signature to the form

Response

Response Header

Response Body

Error Codes

Examples

Example 1: simple use case (with versioning disabled)

Requests

Response

Sample 2: Specifying metadata and ACL using form fields

Requests

Response

Sample 3: using server-side encryption SSE-COS

Requests

Response

Sample 4: using server-side encryption SSE-C

Requests

Response

Sample 5: versioning-enabled

Requests

Response

Sample 6: versioning-suspended

Requests

Response

Example 7: Object key (form field key) uses $ {filename} wildcard

Requests

Response

Sample 8: Specifying the success_action_redirect form field

Requests

Response

Sample 9: Specifying the success_action_status form field

Requests

Response

4. Generating `SignKey`

5. Generating `StringToSign`

6. Generating `Signature`

Example 7: Object key (form field key) uses `$ {filename}` wildcard

Sample 8: Specifying the `success_action_redirect` form field

Sample 9: Specifying the `success_action_status` form field