All Products
Search

This Product

    Object Storage Service:PostObject

    Document Center

    Object Storage Service:PostObject

    Last Updated:Dec 05, 2025

    You can call the PostObject operation to upload an object to a specified bucket using an HTML form.

    Usage notes

    • To upload a file using an HTML form, you must have the oss:PutObject permission. For more information, see Attach a custom policy to a RAM user.

    • The size of an object uploaded using the PostObject operation cannot exceed 5 GB.

    • A PostObject request requires write permissions on the bucket. If the access control list (ACL) of the bucket is public-read-write, you do not need to include signature information. Otherwise, Object Storage Service (OSS) authenticates the signature in the request.

    • Unlike a PutObject operation, a PostObject operation uses an AccessKey secret to sign the policy. The calculated signature string is used as the value of the Signature form field. OSS authenticates this value to determine the validity of the signature.

    • The URL for the submitted form is the bucket's domain name. You do not need to specify the object in the URL. The request line is POST / HTTP/1.1 and not POST /ObjectName HTTP/1.1.

    • If a POST request contains signature information in the header or URL, OSS does not check this information.

    Versioning

    If you send a PostObject request to a versioning-enabled bucket, OSS automatically generates a unique version ID for the new object. This ID is returned in the x-oss-version-id header of the response.

    If you send a PostObject request to a versioning-suspended bucket, OSS automatically generates a null version ID for the new object. This ID is returned in the x-oss-version-id header of the response. Only one null version ID is allowed for the same object.

    Request syntax

    POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length: ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    Request headers

    Important

    • The message body of a PostObject request is encoded in the multipart/form-data format. Unlike a PutObject operation in which parameters are passed in HTTP request headers, a PostObject operation passes parameters as form fields in the message body.

    • You cannot add tags to an object by including the x-oss-tagging request header in a PostObject operation. After the PostObject operation is complete, you can call the PutObjectTagging operation to add tags to the object.

    Name

    Type

    Required

    Description

    Content-Type

    String

    No

    The type of the file and the encoding of the web page. This determines how browsers read and encode the file.

    The form submitted in a Post operation must be encoded in the multipart/form-data format. This means the Content-Type header is in the multipart/form-data;boundary=xxxxxx format.

    The boundary is a random string generated by the form. You do not need to specify it. If you use an SDK to construct the form, the SDK also generates a random value.

    This operation also uses common request headers, such as Host and Date. For more information, see Common request headers.

    Form elements

    The following table describes the form elements that are common to both V1 and V4 signatures. For information about form elements that are unique to V4 signatures, see V4 signature form. For information about form elements that are unique to V1 signatures, see V1 signature form.

    Important

    • The file field must be the last form field. Other form fields can be in any order.

    • The key of a form field cannot exceed 8 KB in size, and the value cannot exceed 2 MB in size.

    Name

    Type

    Required

    Description

    Cache-Control

    String

    No

    Specifies the caching behavior of the web page when the object is downloaded. For more information, see RFC 2616.

    Default value: none.

    Content-Disposition

    String

    No

    Specifies the name of the object when it is downloaded. For more information, see RFC 2616.

    Default value: none.

    Content-Encoding

    String

    No

    Specifies the content encoding format of the object when it is downloaded. For more information, see RFC 2616.

    Default value: none.

    Expires

    String

    No

    The expiration time. For more information, see RFC 2616.

    Default value: none.

    policy

    String

    Yes, conditional

    The policy specifies the validity of the request form fields. A request that does not contain the policy form field is considered an anonymous request and can be used only to access public-read-write buckets.

    Default value: none.

    Constraint: The policy form field is required if the bucket is not public-read-write or if the OSSAccessKeyId or Signature form field is provided.

    Important

    The form and the policy must be UTF-8 encoded. The policy form field must also be Base64-encoded.

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

    String

    No

    The customer master key (CMK) that is managed by KMS. This element is valid only when x-oss-server-side-encryption is set to KMS.

    x-oss-content-type

    String

    No

    Browsers automatically add a Content-Type to the file form field. To address this, OSS supports adding x-oss-content-type to the Post request body. This element lets you specify the Content-Type and has the highest priority.

    Priority order: x-oss-content-type > Content-Type of the file form field

    Default value: none.

    x-oss-forbid-overwrite

    String

    No

    Specifies whether to overwrite an object that has the same name during a PostObject operation.

    When the destination bucket is in the versioning-enabled or versioning-suspended state, the x-oss-forbid-overwrite request header is invalid. This means that an object that has the same name can be overwritten.

    • If you do not specify x-oss-forbid-overwrite or set x-oss-forbid-overwrite to false, an object that has the same name can be overwritten.

    • If you set x-oss-forbid-overwrite to true, an object that has the same name cannot be overwritten.

    Setting the x-oss-forbid-overwrite request header reduces QPS performance. If you have many operations that require the x-oss-forbid-overwrite request header (QPS > 1,000), contact technical support to avoid affecting your business.

    x-oss-object-acl

    String

    No

    Specifies the access permissions of the object in the file form field. This element can be specified in the file form field.

    Valid values:

    • default (default): The object inherits the access permissions 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 on the object. Use this permission 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 permission with caution.

    For more information about access permissions, see Object ACL.

    x-oss-storage-class

    String

    No

    Specifies the storage class of the object.

    For a bucket of any storage class, if you specify this parameter when you upload an object, the uploaded object is stored in the specified storage class. For example, if you specify x-oss-storage-class as Standard when you upload an object to an IA bucket, the object is stored as a Standard object.

    Valid values:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    • 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.

    key

    String

    Yes

    The name of the object to upload. Do not encode the name. If the name includes a path, such as destfolder/example.jpg, OSS automatically creates the corresponding folder.

    Default value: none.

    success_action_redirect

    String

    No

    The URL to which the client is redirected after a successful upload. If this form field is not specified, the returned result is specified by the success_action_status form field. If the upload fails, OSS returns an error code and does not perform a redirection.

    Default value: none.

    success_action_status

    String

    No

    When the success_action_redirect form field is not specified, this form field specifies the status code that is returned to the client after a successful upload.

    Valid values: 200, 201, and 204 (default).

    • If this field is set to 200 or 204, OSS returns an empty document and the corresponding status code.

    • If this field is set to 201, OSS returns an XML file and the 201 status code.

    • If this field is not set or is set to an invalid value, OSS returns an empty document and the 204 status code.

    x-oss-meta-*

    String

    No

    The user-specified user meta.

    Default value: none.

    If the request includes a form field that is prefixed with x-oss-meta-, the field is considered user meta. For example, x-oss-meta-location.

    Note

    An object can have multiple such parameters, but the total size of all user meta cannot exceed 8 KB.

    x-oss-security-token

    String

    No

    The security token. This parameter is required only when you use Security Token Service (STS) to construct a signed URL. You can obtain a security token by calling the AssumeRole operation of STS.

    Default value: none.

    file

    String

    Yes

    The file or text content. Do not encode the content. The browser automatically sets the Content-Type based on the file type and overwrites your settings. OSS can upload only one file at a time.

    Default value: none.

    Important

    The file field must be the last form field.

    Response headers

    Name

    Type

    Example

    Description

    x-oss-server-side-encryption

    String

    KMS

    If the x-oss-server-side-encryption header is specified in the request, the response includes this header to indicate the server-side encryption algorithm used.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    The MD5 hash of the file.

    Important

    The MD5 hash of the file is the MD5 hash obtained after the client completes the upload, not the MD5 hash of the response body.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    The CRC-64 value of the file.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    The version ID of the file. This response header is returned only when you upload a file to a bucket for which versioning is enabled.

    This operation also returns common response headers, such as Date and x-oss-request-id. For more information, see Common response headers.

    Response elements

    Name

    Type

    Description

    PostResponse

    Container

    The container that stores the result of the Post request.

    Child nodes: Bucket, ETag, Key, and Location

    Bucket

    String

    The name of the bucket.

    Parent node: PostResponse

    ETag

    String

    The ETag (Entity Tag) is created when each object is generated. For an object created by a Post request, the ETag is a unique value generated based on a specific calculation rule, but it is not the MD5 hash of the object's content. The ETag can be used to check if the object content has changed.

    Parent node: PostResponse

    Location

    String

    The URL of the newly created object.

    Parent node: PostResponse

    Examples

    • Request example: 

      POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
200
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    • Response example: 

      HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

    SDK

    You can call this operation using the following software development kits (SDKs):

    Error codes

    Error code

    HTTP status code

    Description

    FieldItemTooLong

    400

    The size of the form field key cannot exceed 8 KB, and the size of the form field value cannot exceed 2 MB.

    InvalidArgument

    400

    Regardless of whether the bucket is public-read-write, if any of the OSSAccessKeyId, policy, or Signature form fields are uploaded, the other two form fields are required. If they are missing, this error is returned.

    InvalidDigest

    400

    If you upload a request with the Content-MD5 header, OSS calculates the Content-MD5 of the body and checks for consistency. If they are inconsistent, this error is returned.

    EntityTooLarge

    400

    The total length of the request body cannot exceed 5 GB. If the file is too large, this error is returned.

    InvalidEncryptionAlgorithmError

    400

    If you specify the x-oss-server-side-encryption request header during upload, you must set its value to AES256 or KMS. If you set it to another value, this error is returned.

    IncorrectNumberOfFilesInPOSTRequest

    400

    The number of files in the Post request is invalid. A Post request can contain only one file form field.

    FileAlreadyExists

    409

    If the request header contains x-oss-forbid-overwrite=true, an object that has the same name cannot be overwritten. If the file already exists, this error is returned.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption is specified as KMS, but you have not purchased a KMS suite in advance.

    FileImmutable

    409

    If you try to delete or modify data in a bucket that is protected, this error code is returned.

    MethodNotAllowed

    405

    The HTTP request method is not supported or allowed by the server. Check the request method and headers to ensure that the header information is correct and the service supports the request method. Check the URL to ensure that the protocol, domain name, and path are correct.

    POST policy

    The policy form field is a security policy that is defined in the JSON format. This field specifies permission limits and constraints for uploading files to OSS using an HTML form. The policy uses multiple parameters to limit the upload operation, such as the bucket name, object prefix, validity period, allowed HTTP methods, and limits on upload sizes and content types.

    POST signature

    A POST signature ensures the security of an upload request. When you use the PostObject operation, OSS requires that each upload request includes a signature to verify the legitimacy and security of the request.

    FAQ

    What do I do if the "Your proposed upload exceeds the maximum allowed size" error is returned?

    • Cause: The size of the uploaded file is outside the range specified by content-length-range.

    • Solution: Use content-length-range to specify the minimum and maximum allowed sizes for the uploaded file in bytes. For example, to upload a file of 1 GB, you can set content-length-range to ["content-length-range", 1, 1073741824].

    References