Uploads objects.

  • The size of the object to be uploaded cannot exceed 5 GB.
  • If an object with the same name as an existing object, and you have access to it, the existing object is overwritten by the uploaded object, and the status code 200 OK is returned.
  • OSS does not have a folder. All the data is stored as objects. You can create an empty object as a folder.

Request syntax

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request header

Note OSS supports the following five header fields defined in HTTP: Cache-Control, Expires, Content-Encoding, Content-Disposition, and Content-Type. If these headers are set when you upload an object, the header values are automatically set to the corresponding values when the object is downloaded.
Header Type Required? Description
Authorization String No

Indicates that the request is authorized. For more information, see RFC2616.

Generally, the Authorization request header is required. This header is optional if the URL you use contains a signature. For more information, see Add a signature to a URL.

Default value: None

Cache-control String No Specifies the Web page caching behavior when the object is downloaded. For more information, see RFC2616.

Default value: None

Content-Disposition String No Specifies the name of the object when the object is downloaded. For more information, see RFC2616.

Default value: None

Content-Encoding String No Specifies the content encoding format when the object is downloaded. For more information, see RFC2616.

Default value: None

Content-MD5 String No

Checks whether the message content is consistent with the sent content. The value of Content-MD5 is calculated based on the MD5 algorithm. After the Content-MD5 request header is uploaded, OSS calculates Content-MD5 and checks the consistency.

Default value: None

Content-Length String No

Specifies the data length in the HTTP request body.

If the value of Content-Length in the request header is smaller than the data length in the request body, OSS can still create the object successfully. However, the object size is the value of Content-Length, and the data that exceeds the value is discarded.

ETag String No

An entity tag (ETag) is created to identify the content of an object when the object is created. For an object created with the PutObject request, its ETag is the MD5 value of the object content. For an object created by using other methods, its ETag is the UUID of the object content. The ETag value of an object can be used to check whether the object content has changed. However, we recommend that you not use the ETag of an object as the MD5 value of the object to verify data integrity.

Default value: None

Expires String No

Specifies the expiration time. For more information, see RFC2616.

Default value: None

x-oss-server-side-encryption String No

Specifies the server-side encryption algorithm when OSS creates an object.

Valid values: AES256 and KMS
Note You must enable Key Management Service (KMS) in the console before you can use the KMS encryption algorithm. Otherwise, a KmsServiceNotEnabled error code is reported.

After this header is specified, it will be returned in the response header, and OSS will encrypt and store the uploaded object. When the object is downloaded, the response header will contain x-oss-server-side-encryption and the value will be set to the encryption algorithm of the object.

x-oss-server-side-encryption-key-id String No

Specifies the primary key managed by KMS.

This parameter is valid when the value of x-oss-server-side-encryption is set to KMS.

x-oss-object-acl String No

Specifies the access permission when OSS creates an object.

Valid values: public-read, private, and public-read-write

x-oss-storage-class String No

Specifies the storage class of the object.

If you specify the value of x-oss-storage-class when uploading an object to a bucket, the storage class of the uploaded object is the specified value. For example, if you specify the value of x-oss-storage-class to Standard when uploading an object to a bucket of the IA storage class, the storage class of the object is Standard.

Valid values: Standard, IA, and Archive

Supported APIs: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

x-oss-meta-* String No

When you use the PutObject API, if you configure a parameter prefixed with x-oss-meta-*, this parameter then works as the metadata, such as x-oss-meta-location. An object can have multiple similar parameters. However, the total size of all metadata cannot exceed 8 KB. The metadata can be numbers, hyphens (-), and lowercase letters. Other characters such as underscores (_) are not supported. Uppercase letters are converted to lowercase letters automatically.

x‑oss‑tagging String No
Specifies the tag of the object. You can set multiple tags at the same time, for example, TagA=A&TagB=B.
Note You must perform URL encoding for the tag key and value in advance. If a tag does not contain an equal sign (=), this string does not have a value.


Request example in a simple upload:
PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
date: Tue, 04 Dec 2018 15:56:37 GMT
authorization: OSS qn6qrrqxo2oawuk53otf****:kZoYNv66bsmc10+dcGKw5x2P****
Transfer-Encoding: chunked
Response example
HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422****
ETag: "D41D8CD98F00B204E9800998ECF8427E"
x-oss-hash-crc64ecma: 0
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
x-oss-server-time: 7
Request example in which the storage class is Archive:
PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Encoding: utf-8
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS qn6qrrqxo2oawuk53otf****:kZoYNv66bsmc10+dcGKw5x2P****  
[344606 bytes of object data]
Response example
HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB3044396****
x-oss-bucket-version: 1418321259
ETag: "A797938C31D59EDD08D86188F6D5B872"



How do I calculate Content-MD5?

Calculate the 128bit binary array encrypted by using MD5, and then encode the calculated value by using Base64. For example, you can calculate Content-MD5 of 0123456789 by using the following code in Python:

>>> import base64,hashlib
>>> hash = hashlib.md5()
>>> hash.update("0123456789")
>>> base64.b64encode(hash.digest())

Correct calculation method: use the hash.digest() method to calculate the 128-bit data array >>> hash.digest() 'x\x1e^$]i\xb5f\x97\x9b\x86\xe2\x8d#\xf2\xc7'.

Wrong calculation method: perform Base64 encoding for the calculated 32-bit string. For example, you use the hash.hexdigest() method to calculate the 32-bit string code >>> hash.hexdigest() '781e5e245d69b566979b86e28d23f2c7'. The wrong MD5 value after Base64 encoding is >>> base64.b64encode(hash.hexdigest()) 'NzgxZTVlMjQ1ZDY5YjU2Njk3OWI4NmUyOGQyM2YyYzc='.

Error codes

Error code HTTP status code Description
MissingContentLength 411 The request header is not encoded according to chunked encoding and does not contain the Content-Length parameter.
InvalidEncryptionAlgorithmError 400 The value of x-oss-server-side-encryption is invalid. The valid value is AES256 or KMS.
AccessDenied 403 You do not have the permission to access the bucket to which you want to add an object.
NoSuchBucket 404 The bucket to which you want to add an object does not exist.
InvalidObjectName 400 The length of the uploaded object key exceeds 1,023 bytes.
InvalidArgument 400
  • The uploaded object exceeds 5 GB.
  • Values of the parameters such as x-oss-storage-class are invalid.
RequestTimeout 400 The Content-Length parameter is specified, but the message body is not sent. Or the sent message body is smaller than the specified size. In this case, the sever keeps waiting until times out.
KmsServiceNotEnabled 403 The x-oss-server-side-encryption is specified to KMS. However, you do not enable KMS in advance.