PutObject
Updated at：2025-11-03
API description
This API is used to upload a file to the specified bucket, and the requester must have write permission. Make sure the corresponding bucket exists before PutObject. BOS supports object file sizes ranging from 0 Byte to 5 GB. For files larger than 5 GB, please refer to [Multipart Upload Guide](BOS/API Reference/Multipart Upload-Related Interface/User guide.md).
Request
Plain Text
1PUT /<ObjectName> HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <AuthorizationString>
5Content-Type: text/plain
6Content-Length: <Content_Length>
7x-bce-storage-class: <Storage_class>| Name | Types | Description | Whether required |
|---|---|---|---|
| Cache-Control | String | Cache settings for downloading the Object. Common values include private, no-cache, max-age and must-revalidate |
No |
| Content-Disposition | String | Set whether to download the browser. Options: inline, attachment; filename="download.txt" |
No |
| Content-MD5 | String | The MD5 digest of the HTTP request content, as defined in RFC 2616, verifies data consistency between the file stored in BOS and the one expected by the user. | No |
| Expires | String | This is used to define the cache expiration time for downloaded objects. If no time is set, BOS defaults the cache expiration time to three days. | No |
| x-bce-meta-* | String | User-defined meta | No |
| x-bce-content-sha256 | String | This field verifies consistency between the object stored on BOS and the file expected by the user, with SHA256 offering enhanced validation accuracy. The transmitted data's SHA256 value must match; otherwise, the PutObject operation will fail. | No |
| x-bce-content-crc32 | String | CRC32 value of the uploaded object (IEEE algorithm). | No |
| x-bce-content-crc32c | String | CRC32C value of the uploaded object (Castagnoli algorithm). | No |
| x-bce-content-crc32c-flag | String | CRC32C calculation is only performed when the value is set to "true". | No |
| x-bce-storage-class | String | It specifies the storage class of the object: STANDARD_IA indicates infrequent access storage, COLD indicates cold storage, ARCHIVE indicates archive storage. If not specified, the default class is STANDARD standard storage. For multi-AZ buckets, MAZ_STANDARD_IA indicates multi-AZ infrequent access storage. If not specified, the default class is MAZ_STANDARD multi-AZ standard storage, rather than other options. |
No |
| x-bce-acl | String | Headers supported by CannedACL enable users to set object permissions, allowing either private or public-read access. | No |
| x-bce-grant-read | String | Headers supported by CannedACL allow users to set read permissions for an object. Multiple IDs can be set and should be separated by commas. | No |
| x-bce-grant-full-control | String | Headers supported by CannedACL allow users to set FULL_CONTROL permissions for an object. Multiple IDs can be set and should be separated by commas. | No |
| x-bce-server-side-encryption | String | Server-Side Encryption (SSE) supports AES256 and SM4 encryption algorithms. | No |
| x-bce-forbid-overwrite | Boolen | Whether overwriting is forbidden, defaulting to False. When the value is True, 409 error will be returned when a file of the same name is uploaded next time. | No |
Response
| Name | Types | Description |
|---|---|---|
| ETag | String | The HTTP protocol entity tag of object |
| x-bce-version-id | String | Object version ID |
Note
- Content-Length is a required parameter. If the Content-Length provided by the requester is shorter than the actual request body (the object's actual data), BOS will save only the specified Content-Length data and discard the excess. Conversely, if the Content-Length is longer, BOS will wait for the requester to upload the additional data until a timeout occurs.
- If Content-Type is not specified for uploaded objects, BOS will automatically recognize and set an appropriate Content-Type. If unrecognized, it defaults to
application/octet-stream- Since BOS is inherently a (
<Key>,<Value>) storage system, the concept of "folder" does not exist in principle. If it is necessary to divide by folder, the "/" symbol can be used as a delimiter to simulate folders. If an object is uploaded as "work/test/123.txt", it will be automatically split by "/" for display in the console, creating a test folder in the work folder and a 123.txt file in the test folder.
Example
Plain Text
1PUT /ObjectName HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Type: text/plain
6Content-Length: 11434
7x-bce-storage-class: STANDARD_IA
8[11434 bytes of object data]
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4ETag: "1b2cf535f27731c974343645a3985328"
5x-bce-version-id:AJyQ0XRhboY=
6Content-Length: 0
7Connection: close
8Server: BceBos