InitiateMultipartUpload

Call InitiateMultipartUpload to initialize a multipart upload before uploading data in parts to OSS.

Notes

The InitiateMultipartUpload operation returns a globally unique upload ID. Use this ID for subsequent operations such as aborting or querying the multipart upload.
Initializing a multipart upload does not affect an existing object that has the same name.
When you calculate a signature to authenticate the InitiateMultipartUpload operation, add ?uploads to CanonicalizedResource.
Initializing a multipart upload requires the oss:PutObject permission, which you can configure in Grant custom permissions to a RAM user.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
InitiateMultipartUpload	`oss:PutObject`	Initializes multipart upload tasks.
	`oss:PutObjectTagging`	When initializing a multipart upload task, if you specify object tags through x-oss-tagging, this permission is required.
	`kms:GenerateDataKey`	When uploading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, these two permissions are required.
	`kms:Decrypt`

Request syntax

POST /ObjectName?uploads HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT date
Authorization: SignatureValue

When you call this operation in OSS on Cloud Box, you need to replace the Host with the CloudBox endpoints. For more information, see CloudBox endpoints。

Request headers

InitiateMultipartUpload supports standard HTTP request headers (Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires) and custom headers prefixed with x-oss-meta-. These headers follow the same rules as PutObject.

Name	Type	Description
Cache-Control	String	Specifies the web page caching behavior when the object is downloaded, as defined in RFC 2616. Default value: none
Content-Disposition	String	Specifies the download filename for the object, as defined in RFC 2616. Default value: none
Content-Encoding	String	Specifies the content encoding of the object, as defined in RFC 2616. Default value: none
Expires	String	The expiration time, as defined in RFC 2616. Default value: none
x-oss-forbid-overwrite	String	Specifies whether to overwrite an existing object with the same name. If versioning is enabled or suspended for the bucket, x-oss-forbid-overwrite is ignored and the existing object is overwritten. If x-oss-forbid-overwrite is not specified or x-oss-forbid-overwrite is set to false, the existing object is overwritten. If x-oss-forbid-overwrite is set to true, the existing object cannot be overwritten. Setting x-oss-forbid-overwrite reduces QPS performance. If you use x-oss-forbid-overwrite at high volume (QPS > 1,000), contact technical support to prevent business interruptions.
x-oss-server-side-encryption	String	The server-side encryption method used to encrypt each part of the object. Valid values: AES256, KMS, or SM4 Important In OSS on CloudBox scenarios, only AES256 is supported. To use the KMS encryption algorithm, you must activate Key Management Service (KMS). If specified, OSS encrypts each uploaded part with the specified method and includes this header in both the upload and download responses. The header value in the download response indicates the encryption algorithm of the object.
x-oss-server-side-data-encryption	String	The encryption algorithm of the object. If this header is not specified, the object is encrypted using the AES256 algorithm. This header is valid only when x-oss-server-side-encryption is set to KMS. Valid value: SM4 Note This header is not supported in OSS on CloudBox scenarios.
x-oss-server-side-encryption-key-id	String	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. Note This header is not supported in OSS on CloudBox scenarios.
x-oss-storage-class	String	The storage class of the object. If specified, the object uses this storage class regardless of the bucket's default. For example, setting x-oss-storage-class to Standard stores the object as Standard even in an IA bucket. Valid values: Standard Note If you use OSS on CloudBox, only the Standard storage class is supported. IA (Infrequent Access) Archive (Archive Storage) ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Important If you want to upload a large number of objects, directly specifying the Deep Cold Archive storage class for the objects to be uploaded results in high PUT request fees. We recommend that you first specify the Standard storage class for the objects when you upload them, and then use lifecycle rules to convert them to the Deep Cold Archive storage class to reduce PUT request fees. Storage classes.
x-oss-tagging	String	The object tag. You can specify multiple tags. Example: TagA=A&TagB=B Note Tag keys and values must be URL-encoded. If a tag does not contain an equal sign (`=`), the value is an empty string.

Request parameters

Specify the encoding-type parameter to encode the object name in the response.

Name

Type

Description

encoding-type

String

The encoding method for the object name in the response. Object names are encoded in UTF-8, but XML 1.0 does not support certain control characters (ASCII values 0 to 10). Use this parameter to encode object names that contain such characters.

Default value: none

Valid value: url

Response elements

OSS returns an XML response containing the following elements:

Name	Type	Description
InitiateMultipartUploadResult	Container	The container for InitiateMultipartUpload results. Child nodes: Bucket, Key, UploadId, and EncodingType Parent node: None
Bucket	String	The bucket name for the multipart upload event. Parent node: InitiateMultipartUploadResult
Key	String	The object name for the multipart upload event. Parent node: InitiateMultipartUploadResult
UploadId	String	The unique ID for the multipart upload event. Use this ID in subsequent UploadPart and CompleteMultipartUpload calls. Parent node: InitiateMultipartUploadResult
EncodingType	String	The encoding type of the object name in the response. Present only when the encoding-type parameter is specified in the request. Parent node: InitiateMultipartUploadResult

This operation also returns Common response headers.

Examples

Sample request

POST /multipart.data?uploads HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Wed, 22 Feb 2012 08:32:21 GMT 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
Content-Length: 230
Server: AliyunOSS
Connection: keep-alive
x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eae****
Date: Wed, 22 Feb 2012 08:32:21 GMT
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <UploadId>0004B9894A22E5B1888A1E29F823****</UploadId>
</InitiateMultipartUploadResult>

SDK

SDKs for this operation:

ossutil command-line tool

Corresponding ossutil command: initiate-multipart-upload.

Error codes

Error code	HTTP status code	Description
InvalidEncryptionAlgorithmError	400	A server-side encryption method other than AES256, KMS, or SM4 is specified.
InvalidArgument	400	The x-oss-server-side-encryption request header is added when each part is uploaded.
InvalidArgument	400	The specified storage class is invalid.
KmsServiceNotEnabled	403	The KMS encryption algorithm is used, but KMS is not activated in the console.
FileAlreadyExists	409	When the request header contains x-oss-forbid-overwrite=true, you cannot overwrite a file that has the same name. This fault is returned if a file with the same name already exists.