Object Storage Service PutObject API - Object Storage Service

The PutObject operation uploads an object to a bucket in Object Storage Service (OSS). The size of an object in a single upload cannot exceed 5 GB.

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

Usage notes

The maximum size of an object that can be uploaded in a single operation is 5 GB. To upload an object larger than 5 GB, use multipart upload.
By default, if you upload an object with the same name as an existing object, OSS overwrites the object and returns a 200 OK status code. You can set a parameter to prevent overwrites and avoid accidentally overwriting important objects.
OSS uses a flat storage structure and lacks the concept of directories found in traditional file systems. You can simulate a folder structure by creating an empty object with a name that ends with a forward slash (/).

Permissions

By default, an Alibaba Cloud account has full permissions. By default, a RAM user or RAM role has no permissions. An Alibaba Cloud account or an account administrator must grant permissions by using a RAM Policy or a Bucket Policy.

API	Action	Description
PutObject	`oss:PutObject`	Uploads an object.
	`oss:PutObjectTagging`	Required if you specify object tags by using the `x-oss-tagging` header when you upload an object.
	`kms:GenerateDataKey`	Required if the `X-Oss-Server-Side-Encryption: KMS` header is set to `KMS` when you upload an object.
	`kms:Decrypt`

Versioning

If versioning is enabled for a bucket, OSS automatically generates a unique version ID for each new object. This version ID is returned in the x-oss-version-id response header.

If versioning is suspended for a bucket, the version ID of a new object is null. OSS ensures that only one null version of an object can exist in the bucket.

Request parameters

OSS supports standard HTTP request headers such as Cache-Control, Expires, Content-Encoding, Content-Disposition, and Content-Type. When you set these headers in the upload request, their values are automatically applied when the object is downloaded.

Common Response Headers.

Parameter	Type	Required	Example	Description
Authorization	String	No	OSS qn6q************:77Dv**************	Authenticates and authorizes the request. For more information about how to calculate the signature, see Include a signature in the header. The Authorization header is typically required. However, you do not need to include this header if a signature is included in the URL. For more information, see Include a signature in the URL. Default value: none
Cache-Control	String	No	no-cache	Specifies the caching behavior when an object is downloaded. Valid values: no-cache: The cache must re-validate the content with the origin server before serving it. If the content has changed, the server returns the new object. Otherwise, it confirms the cached version is still valid. no-store: All content of the object is not cached. public: All content of the object is cached. private: All content of the object is cached only on the client. max-age=<seconds>: The validity period of the cached content. Unit: seconds. This option is available only in HTTP 1.1. Default value: none
Content-Disposition	String	No	attachment	Specifies how the object is displayed. Valid values: Content-Disposition:inline: The object is displayed directly in the browser. Content-Disposition:attachment: The object is downloaded to the specified download path of the browser with the original object name. Content-Disposition:attachment; filename="yourFileName": The object is downloaded to the specified download path of the browser with a custom object name. yourFileName specifies the custom name of the downloaded object, such as example.jpg. If you want to download the object to the specified download path of the browser, take note of the following items: Note If the name of the object contains special characters such as asterisks () or forward slashes (/), the name of the downloaded object may be escaped. For example, if you download `example.jpg` to your local computer, `example.jpg` may be escaped as `example_.jpg`. To ensure that object names containing non-ASCII characters (like Chinese) are correctly handled during download and do not result in garbled filenames, you must URL-encode the Chinese characters in the object name. For example, to ensure that the `Test.txt` object in OSS is downloaded as a local file that has the original object name `Test.txt`, you must set the Content-Disposition header to `attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename=UTF-8''%E6%B5%8B%E8%AF%95.txt`, which derives from `"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt"`. Whether an object is previewed or downloaded as an attachment when the object is accessed by using the object URL is determined by the creation time of the bucket in which the object is stored, the activation time of OSS, and the domain name type. For more information, see What do I do if an image object is downloaded as an attachment but cannot be previewed when I access the image object by using its URL? Default value: none
Content-Encoding	String	No	identity	Specifies the encoding of the object. You must set this header to the actual encoding type of the object. Otherwise, client-side parsing or download errors may occur. If the object is not encoded, leave this header empty. Valid values: identity (default): OSS does not compress or encode the object. gzip: OSS uses the LZ77 compression algorithm created by Lempel and Ziv in 1977 and 32-bit cyclic redundancy check (CRC) to encode the object. compress: OSS uses the Lempel–Ziv–Welch (LZW) compression algorithm to encode the object. deflate: OSS uses the zlib library and the deflate algorithm to encode the object. br: OSS uses the Brotli algorithm to encode the object. Default value: none
Content-MD5	String	No	eB5eJF1ptWaXm4bijSPyxw==	Used to check the integrity of the message content. The Content-MD5 header is a value that is generated by using the MD5 algorithm. If you set this header, OSS calculates the Content-MD5 value of the message body and checks whether it matches the value that you provided. For more information, see Calculate Content-MD5 values. To ensure data integrity, OSS offers multiple methods to verify MD5 hash values. If you want to use Content-MD5 for verification, include the Content-MD5 header in your request. Default value: none
Content-Length	String	No	344606	The size of the HTTP message body to be transferred, in bytes. If the value of the Content-Length header is smaller than the actual size of the data in the request body, OSS still creates the object. However, the object size is equal to the size specified in Content-Length, and the excess data is discarded.
Expires	String	No	Wed, 08 Jul 2015 16:57:01 GMT	Specifies the expiration time of the object. For more information, see RFC2616. Default value: none
x-oss-forbid-overwrite	String	No	false	Specifies whether to overwrite an object that has the same name during a PutObject operation. If versioning is enabled or suspended for the destination bucket, the x-oss-forbid-overwrite request header is ignored, and existing objects can be overwritten. If you do not specify x-oss-forbid-overwrite, or if you set x-oss-forbid-overwrite to false, you can overwrite an Object with the same name. If you set x-oss-forbid-overwrite to true, an existing object with the same name cannot be overwritten. Setting the x-oss-forbid-overwrite request header affects QPS processing performance. If you use the x-oss-forbid-overwrite request header for a large number of operations (QPS > 1000), contact technical support to avoid affecting your business operations. Default value: false
x-oss-server-side-encryption	String	No	AES256	Specifies the server-side encryption method to use when you create an object. Valid values: AES256, KMS If you specify this header, it is returned in the response. OSS encrypts the uploaded object. When you download the object, the response includes the x-oss-server-side-encryption header, and its value is set to the encryption algorithm of the object.
x-oss-server-side-encryption-key-id	String	No	9468da86-3509-4f8d-a61e-6eab1eac****	The ID of the customer master key (CMK) that is managed by KMS. This header is valid only when x-oss-server-side-encryption is set to KMS.
x-oss-object-acl	String	No	default	Specifies the access control list (ACL) of the object when it is created. Valid values: default (default): The object inherits the ACL of the bucket. private: The object is a private resource. Only the object owner and authorized users have read and write permissions on the object. Other users cannot access the object. public-read: The object is a public-read resource. Only the object owner and authorized users have read and write permissions on the object. Other users have only read permissions. Use this ACL with caution. public-read-write: The object is a public read/write resource. All users have read and write permissions on the object. Use this ACL with caution. For more information about ACLs, see Object ACL.
x-oss-storage-class	String	No	Standard	Specifies the storage class of the object. For a bucket of any storage class, if you specify this header when you upload an object, the object is stored in the specified storage class. For example, if you set x-oss-storage-class to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object. Valid values: Standard: Standard IA: Infrequent Access Archive: Archive ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Important Setting the storage class to Deep Cold Archive during upload incurs higher PUT request fees. We recommend that you set the storage classes of the objects to Standard when you upload the objects, and configure lifecycle rules to convert the storage classes of the Standard objects to Deep Cold Archive. This reduces PUT request fees. For more information, see Storage classes.
x-oss-meta-*	String	No	x-oss-meta-location	When you call the PutObject operation, headers that start with the x-oss-meta- prefix are considered user-defined metadata. For example, `x-oss-meta-location`. An object can have multiple user-defined metadata headers, but their total size cannot exceed 8 KB. User-defined metadata supports hyphens (-), digits, and letters. OSS converts uppercase letters to lowercase. Other characters, including underscores (_), are not supported.
x-oss-tagging	String	No	TagA=A&TagB=B	Specifies one or more key-value tags for the object. For example: `TagA=A&TagB=B`. Note A key and a value must be URL-encoded. A key is required, but a value is optional. For example, you can set an object tag to `TagA&TagB=B`.
x-oss-object-worm-mode	String	No	COMPLIANCE	Specifies the mode of the retention policy for the object. The value is `COMPLIANCE`. This header is valid only for buckets for which ObjectWorm is enabled. If you set this header, you must also set `x-oss-object-worm-retain-until-date`.
x-oss-object-worm-retain-until-date	String	No	2026-09-30T00:00:00.000Z	Specifies the expiration date of the retention policy. The date must be in ISO 8601 format. This header is valid only for buckets for which ObjectWorm is enabled. Before the specified expiration date, the object cannot be deleted or overwritten. If you do not specify this header, the default retention rule of the bucket is applied to the uploaded object, if a default rule is configured.

Response parameters

Parameter	Type	Example	Description
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	The MD5 hash of the uploaded object. Important This is the MD5 hash of the uploaded object, not the MD5 hash of the response body.
x-oss-hash-crc64ecma	String	316181249502703****	The CRC-64 hash of the uploaded object.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	The version ID of the uploaded object. OSS returns this header only if the bucket has versioning enabled.

For more information about common response headers, see Common Response Headers.

Examples

Simple upload

Request

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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-zhangjiakou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Response

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: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

Set storage class

Request

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-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpeg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[344606 bytes of object data]

Response

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpeg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

Enable versioning

Request

PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

Error codes

Error code	HTTP status code	Description
MissingContentLength	411	The request does not use chunked encoding, or the Content-Length parameter is not set.
InvalidEncryptionAlgorithmError	400	The value specified for x-oss-server-side-encryption is invalid. Valid values: AES256, KMS.
AccessDenied	403	You do not have the required permissions to access the specified bucket when you upload the object.
NoSuchBucket	404	The specified bucket does not exist when you upload the object.
InvalidObjectName	400	The object name is invalid. The object name might not be specified, might exceed the length limit, or might be invalid.
InvalidArgument	400	Possible causes: The object size exceeds 5 GB. The value of a parameter such as x-oss-storage-class is invalid.
RequestTimeout	400	Content-Length is specified, but no message body is sent, or the sent message body is smaller than the specified size. In this case, the server waits until the request times out.
Bad Request	400	If you specify Content-MD5 in the request, OSS calculates the MD5 hash of the data that is sent and compares it with the value of Content-MD5 in the request. If the two values do not match, this error is returned.
KmsServiceNotEnabled	403	You specified KMS for x-oss-server-side-encryption but have not purchased a KMS suite.
FileAlreadyExists	409	The possible reasons for this error are as follows: The request header includes `x-oss-forbid-overwrite=true`, but an object with the same name already exists in the bucket. The hierarchical namespace feature is enabled for the bucket, and a directory with the same name already exists at the current directory level.
FileImmutable	409	OSS returns this error if you attempt to modify an object protected by a retention policy.

Integration methods

SDK
You can call the PutObject API by using the following SDKs:
Java
Python V2
Go V2
C++
PHP V2
C
.NET
Android
iOS
Node.js
Browser.js
Ruby
Harmony
ossutil command-line tool
For information about the ossutil command that corresponds to the PutObject operation, see put-object.

FAQ

How to modify object metadata

You can modify object metadata by using the OSS console, ossbrowser, SDKs for various languages, the ossutil command-line tool, or the REST API. For example, you can change the Content-Type from application/octet-stream to image/jpeg. For more information, see Manage object metadata.

Why is the Expires header not working?

Cache header priority
If you set both Expires and Cache-Control, Cache-Control takes precedence. If Cache-Control includes a caching directive such as max-age=3600, the Expires header may be ignored.

Expires is incorrectly set

The Expires header requires a value that is a future time in GMT format. The following code provides an example of how to set this header by using the Node.js SDK:

const OSS = require('ali-oss');

// Create an OSS client instance.
const client = new OSS({
  // Replace yourregion with the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the bucket name.
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// Set the absolute expiration time for the cached content.
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);

Java	Python V2	Go V2	C++	PHP V2
C	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony