All Products
Search

This Product

    Object Storage Service:PostObject

    Document Center

    Object Storage Service:PostObject

    Last Updated:May 27, 2026

    Call the PostObject operation to upload an object to a bucket by using an HTML form.

    Usage notes

    • Uploading by HTML form requires the oss:PutObject permission. Attach a custom policy to a RAM user.

    • Objects uploaded by PostObject cannot exceed 5 GB.

    • A PostObject request requires write permissions on the bucket. If the bucket ACL is public-read-write, signature information is not required. Otherwise, OSS authenticates the signature in the request.

    • Unlike PutObject, PostObject uses an AccessKey secret to sign the policy. The resulting signature string is the value of the Signature form field, which OSS authenticates.

    • The form URL is the bucket domain name without the object name. The request line is POST / HTTP/1.1, 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 versioning is enabled on the bucket, OSS generates a unique version ID for the uploaded object and returns it in the x-oss-version-id response header.

    If versioning is suspended, OSS generates a null version ID for the uploaded object and returns it in the x-oss-version-id response header. Only one null version ID is allowed per 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 PostObject request body uses multipart/form-data encoding. Unlike PutObject, which passes parameters in HTTP headers, PostObject passes parameters as form fields in the body.

    • PostObject does not support the x-oss-tagging header. After PostObject completes, call PutObjectTagging to tag the object.

    Name

    Type

    Required

    Description

    Content-Type

    String

    No

    The file type and web page encoding, which determines how browsers read 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. SDKs generate this value automatically.

    This operation also uses Common request headers such as Host and Date.

    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

    The caching behavior when the object is downloaded, as defined in RFC 2616.

    Default value: none.

    Content-Disposition

    String

    No

    The download filename for the object, as defined in RFC 2616.

    Default value: none.

    Content-Encoding

    String

    No

    The content encoding of the object when downloaded, as defined in RFC 2616.

    Default value: none.

    Expires

    String

    No

    The cache expiration time, as defined in RFC 2616.

    Default value: none.

    policy

    String

    Yes, conditional

    Specifies the validity of the request form fields. A request without the policy field is treated as anonymous and can only access public-read-write buckets.

    Default value: none.

    Constraint: Required if the bucket is not public-read-write, or if OSSAccessKeyId or Signature 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 KMS-managed customer master key (CMK). Valid only when x-oss-server-side-encryption is set to KMS.

    x-oss-content-type

    String

    No

    Overrides the Content-Type that browsers automatically add to the file form field. This element has the highest priority for specifying Content-Type.

    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 versioning is enabled or suspended, x-oss-forbid-overwrite is ignored and same-name objects can be overwritten.

    • If x-oss-forbid-overwrite is unspecified or x-oss-forbid-overwrite is set to false, same-name objects can be overwritten.

    • If x-oss-forbid-overwrite is set to true, same-name objects cannot be overwritten.

    The x-oss-forbid-overwrite header reduces QPS. If your x-oss-forbid-overwrite usage exceeds 1,000 QPS, contact technical support.

    x-oss-object-acl

    String

    No

    The access permissions for the uploaded object.

    Valid values:

    • default (default): Inherits the bucket ACL.

    • private: Only the owner and authorized users can read and write the object.

    • public-read: All users can read the object. Only the owner and authorized users can write. Use with caution.

    • public-read-write: All users can read and write the object. Use with caution.

    Access permissions are described in Object ACL.

    x-oss-storage-class

    String

    No

    Specifies the storage class of the object.

    Regardless of the bucket storage class, the uploaded object uses the class you specify. For example, specifying x-oss-storage-class as Standard for an IA bucket stores the object as Standard.

    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.

    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 redirect the client to after a successful upload. If unspecified, the response behavior is determined by success_action_status. On failure, OSS returns an error without redirecting.

    Default value: none.

    success_action_status

    String

    No

    The HTTP status code returned after a successful upload when success_action_redirect is not specified.

    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

    User-defined metadata.

    Default value: none.

    Form fields prefixed with x-oss-meta- are stored as user metadata. 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 STS security token. Required only when using STS to construct a signed URL. Obtain a token by calling the AssumeRole operation.

    Default value: none.

    file

    String

    Yes

    The file or text content. Do not encode the content. The browser sets Content-Type based on the file type, overwriting your settings. Only one file can be uploaded per request.

    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

    Returned if x-oss-server-side-encryption is specified in the request. Indicates the encryption algorithm used.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    The MD5 hash of the file.

    Important

    This is the MD5 hash of the uploaded file, 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 uploaded object. Returned only for versioning-enabled buckets.

    This operation also returns Common response headers such as Date and x-oss-request-id.

    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 of the uploaded object. For PostObject uploads, the ETag is a unique identifier but not the MD5 hash of the content. Use it to verify whether the 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

    Supported 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 bucket ACL, if any of OSSAccessKeyId, policy, or Signature is provided, all three are required. Missing any one returns this error.

    InvalidDigest

    400

    The Content-MD5 in the request does not match the MD5 hash calculated by OSS for the request body.

    EntityTooLarge

    400

    The request body exceeds the 5 GB size limit.

    InvalidEncryptionAlgorithmError

    400

    The x-oss-server-side-encryption value is not AES256 or KMS.

    IncorrectNumberOfFilesInPOSTRequest

    400

    A PostObject request can contain only one file form field.

    FileAlreadyExists

    409

    An object with the same name exists and x-oss-forbid-overwrite is set to true.

    KmsServiceNotEnabled

    403

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

    FileImmutable

    409

    The bucket is protected and data cannot be deleted or modified.

    MethodNotAllowed

    405

    The HTTP request method is not supported. Verify that the request method, headers, URL protocol, domain name, and path are correct.

    POST policy

    The policy form field is a JSON-formatted security policy that specifies constraints for HTML form uploads, including the bucket name, object prefix, validity period, allowed HTTP methods, upload size limits, and content types.

    POST signature

    Each PostObject request must include a signature for authentication.

    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