All Products
Search

This Product

    Object Storage Service:initiate-multipart-upload

    Document Center

    Object Storage Service:initiate-multipart-upload

    Last Updated:Dec 06, 2025

    The initiate-multipart-upload command initiates a multipart upload task.

    Usage notes

    • When you run the initiate-multipart-upload command, Object Storage Service (OSS) creates and returns a globally unique upload ID to identify the multipart upload task. You can use this ID to perform related operations, such as aborting or querying the multipart upload.

    • Initiating a multipart upload request does not affect an existing object that has the same name.

    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 Policy or Bucket policies.

    API

    Action

    Definition

    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

    Command syntax

    ossutil api initiate-multipart-upload --bucket value --key value [flags]

    Parameter

    Type

    Description

    --bucket

    string

    The name of the bucket.

    --key

    string

    The full path of the object.

    --encoding-type

    string

    Specifies the encoding of the returned content.

    --content-encoding

    string

    The content encoding format of the object when the object is downloaded.

    --content-type

    string

    The content type of the object.

    --content-disposition

    string

    The name of the object when the object is downloaded.

    --cache-control

    string

    The caching behavior of the web page when the object is downloaded.

    --metadata

    stringArray

    The user metadata of the object in the key=value format. To specify custom metadata, you must configure parameters prefixed with x-oss-meta-*.

    --server-side-data-encryption

    string

    The encryption algorithm of the object.

    --server-side-encryption

    string

    The server-side encryption method that is used to encrypt each part of the object that you want to upload.

    --server-side-encryption-key-id

    string

    The ID of the customer master key (CMK) that is managed by Key Management Service (KMS).

    --storage-class

    string

    The storage class of the object.

    --tagging

    string

    The tags of the object.

    --expires

    string

    The expiration time in milliseconds.

    --forbid-overwrite

    string

    Specifies whether to overwrite an object that has the same name when you call the CompleteMultipartUpload operation.

    Note

    Examples

    • Initiate a multipart upload task.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject

    • Initiate a multipart upload task and display the result in JSON format.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --output-format json

    • Initiate a multipart upload task and display the result in YAML format.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --output-format yaml

    • Initiate a multipart upload task and specify custom metadata.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --metadata user=aliyun --metadata email=ali***@aliyuncs.com

    • Initiate a multipart upload task and specify object tags.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --tagging "TagA=A&TagB=B"

    • Initiate a multipart upload task and specify the server-side encryption method for the object.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --server-side-encryption KMS --server-side-data-encryption SM4 --server-side-encryption-key-id 9468da86-3509-4f8d-a61e-6eab1eac****

    • Initiate a multipart upload task and prevent overwriting an object that has the same name.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --forbid-overwrite true

    • Initiate a multipart upload task and specify the web page caching behavior when the object is downloaded.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --cache-control no-cach

    • Initiate a multipart upload task and specify the name of the object when it is downloaded.

      ossutil api initiate-multipart-upload --bucket examplebucket --key exampleobject --content-disposition "attachment;filename=oss_download.jpg"