Torch Object Storage
Torch Object Storage
Torch Object Storage
Document
What's New
Announcements
Billing
Billable items
Billing method
Getting Started
User Guide
Working with buckets
Basic configurations
Managing lifecycle
Back-to-origin rules
Event notification
Intelligent Tiering
Domain management
Fault tolerance and disaster recovery
Cross-region replication
Same-region replication
Data redundancy
Image processing
ObjectSet
Working with objects
Managing folders
Monitoring and alerting
Metric monitoring
Access control
Bucket policies
Common configuration scenarios
Authorizing IAM users of the current account
Authorizing other accounts
Managing access via tools and SDKs
Managing public read access
Data security
Access points
Multi-region access points (MRAP)
Single-region access points (SRAP)
Converged access points (CAP)
DevMind
TOS accelerator
SenseFlow
TOS Agent
Data processing
Basic concepts
Image processing
Media processing
Document preview
Task processing
Data subscription
Flow control management
Quality of Service (QoS) policies
Hierarchical namespace (HNS)
User guide
Tool reference
Best practices
TOS Vectors
User guide
API reference
Vector bucket
Vector index
SDK reference
Python-Vectors
Vector bucket
Vector index
Java-Vectors
Vector bucket
Vector index
Node.js-Vectors
Vector bucket
Vector index
Tool Guide
tosutil
Common commands
Upload, download, and copy objects
Share objects
Auxiliary commands
Common examples
TOS Browser
FSX
FSX best practices
TOS PyTorch Connector
tosfsspec
TOS Import（will be deprecated soon）
API Reference
Signature Mechanism
The header contains a signature
Bucket
Basic Bucket Operations
Bucket Lifecycle
Access Monitor
Bucket ACL
Bucket CORS
Bucket Policy
Back-to-origin Rules
Bucket Replication
Versioning
Static Website
Event Notification
Custom Domain
Server-side encryption
Transfer Acceleration
Data Processing
Image processing
Media processing
Video transcoding
Audio transcoding
video to GIF
Document preview
File decompression
Log Storage
Retention Policy
Requester pays
TLS version
Object
Basic Object Operations
Object ACL
Fetch Object
Symbolic Link
WORM object
Multipart Upload
SDK Reference
Java
Pre-signing Mechanism
Bucket Interface
Basic Bucket Interface
Manage Bucket Configuration
Object Interface
Upload Object
Download Object
Upload and Download Speed Limit
Copy Object
List Object
Data Processing
Image Processing
Video Processing
Audio Processing
Log Configuration
Hierarchical Namespace
Bucket base interface
Introduction to Typical Scenes
Python
Data processing
Pre-signature mechanism
Bucket interface
Basic bucket interface
Manage bucket configuration
Object interface
Upload object
Download object
Copy object
List objects
Introduction to typical scenes
C
Object Interface
Upload object
C++
Pre-signature Mechanism
Bucket Interface
Basic Bucket Interface
Manage Bucket Configuration
Object Interface
Upload Object
Download Object
Copy Object
List Objects
Data Processing
Go
Object Interface
Upload Object
Download Object
Copy Object
List Objects
Manage Objects
Bucket Interface
Manage Bucket Configuration
Data Processing
Log Configuration
Introduction to Typical Scenes
Pre-signature Mechanism
Node.js
Pre-signature Mechanism
Bucket Interface
Basic Bucket Interface
Manage Bucket Configuration
Object Interface
Upload object
Download object
Copy object
List objects
Data Processing
Image Processing
Introduction to Typical Scenes
Browser.js
Pre-signature Mechanism
Upload Object
Download Object
Copy Object
List Objects
Manage Objects
Data Processing
.NET
Bucket Interface
Object Interface
Upload Object
Download Object
List Objects
Introduction to Typical Scenes
PHP
Bucket Interface
Object Interface
Download Object
Data Processing
Exception Handling
Android
Bucket Interface
Object Interface
Upload Object
Download Object
Exception Handling
iOS
Bucket Interface
Object Interface
Upload Object
Download Object
Harmony
Pre-signature Mechanism
Bucket Interface
Object Interface
Upload Object
Download Object
List Objects v2
Introduction to Typical Scenarios
Rust
Pre-signing mechanism
Bucket interface
Basic bucket operations
Lifecycle rules
Bucket ACLs
Cross-origin resource sharing
Bucket inventory
Back-to-origin rules
Bucket replication
Static website hosting
Event notification
Custom domain
Server-side encryption
Object interface
Basic operation
Access control
Error Codes
01-SERVICE_ERROR
02-AUTH
03-ACCESS_CONTROL
04-QOS
05-REQUEST
06-BUCKET
07-LIFECYCLE
08-ACL
09-CORS
10-POLICY
11-MIRROR
12-REPLICATION
13-WEBSITE
14-NOTIFICATION
15-ENCRYPT
16-CUSTOMDOMAIN
17-OBJECT
18-TAG
19-MULTIPART
20-STORAGE_CLASS
21-CALLBACK
22-DATA_PROCESS
23-BATCH
24-STORAGE_LENS
25-INVENTORY
26-DIRECTORY_BUCKET
FAQ
Best Practices
AIGC-Doubao LLMs
Accessing TOS with third-party tools
Granting temporary access
Data migration
Data processing
Checking data integrity
Performance optimization
- Documentation
Torch Object StorageAPI ReferenceObjectBasic Object OperationsPostObject
Copy page
Download PDFBasic Object Operations
PostObject
Copy pageDownload PDFPostObject
Function Description
This interface enables uploading local objects of up to 5GiB to a specified storage bucket via an HTML form. The requester of this interface must have write permission on the bucket.
Precautions
- The size of form data and boundaries (excluding file content) must not exceed 20KiB.
- Requests without a policy in the form field are considered anonymous and can only succeed on buckets that are publicly writable.
- When constructing a request, ensure that the file field is the last field in the form (fields after file will be ignored).
- The size of the uploaded object must not exceed 5 GiB.
Request syntax
POST / HTTP/1.1
Host: buketname.tos-cn-beijing.volces.com
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length
--9431149156168
Content-Disposition: form-data; name="key"
objectname
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="x-tos-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-tos-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=download.jpg
--9431149156168
Content-Disposition: form-data; name="x-tos-algorithm"
TOS4-HMAC-SHA256
--9431149156168
Content-Disposition: form-data; name="x-tos-date"
20220411T000000Z
--9431149156168
Content-Disposition: form-data; name="x-tos-credential"
<your-access-key-id>/<date>/<region>/<service>/request
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="x-tos-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 TOS
--9431149156168--
Request parameters and headers
This operation is implemented without using request parameters.
Request body elements
Name | Type | Required | Sample value | Description |
policy | String | Yes, with conditions. | eyJleHBpcmF0aW9uIjoiMjAyMi0wMS0wNVQwMDowMDowM C4wMDBaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZXhhbXB sZWJ1Y2tldCJ9LFsic3RhcnRzLXdpdGgiLCIka2V5IiwiZXhhbX BsZSJdXX0= | Security policy encoded in Base64, describing the content permitted in the request. Default value: None warning If the storage bucket does not allow public write access, a policy must be included. When a policy is included, signature-related form fields must also be provided. |
x-tos-algorithm | String | Yes, conditional | TOS4-HMAC-SHA256 | This parameter specifies the signature algorithm used. For TOS, this value is TOS4-HMAC-SHA256. warning If the request includes the security policy parameter, this parameter must be provided. |
x-tos-credential | String | Yes, with conditions. | testAK/20220101/cn-beijing/tos/request | In addition to your access key ID, this also provides the scope information used when calculating the signature key for signature computation. The format is <your-access-key-id>/<date>/<region>/tos/request. warning If the security policy parameter is to be included in the request, it must be provided. |
x-tos-date | String | Yes, with conditions. | 20220101T000000Z | Date value in ISO8601 format. For example, 20130728T000000Z. The date must be identical to the one used when creating the signature key, and must also match the value specified as x-tos-date in the policy. warning If the request includes the security policy parameter, this parameter must be provided. |
x-tos-signature | String | Yes, conditional | 94d72cb3bbd094f6d8eaa0b7e56905500029813febc9fee352474f88d093c3e5 | HMAC-SHA256 hash value calculated based on the security policy (policy) and SigningKey. warning If the request includes the security policy parameter, a value for this parameter must be provided. |
x-tos-acl | String | No | public-read | Specify the access permissions for the Object in the file form field.
|
x-tos-tagging | String | No | { "TagSet": { "Tags": [{ "Key": "Tag1", "Value": "Tag1" }, { "Key": "Tag2", "Value": "Tag2" }] } } | To be added to the specified tag set of the object. Default value: None |
key | String | Yes | exampleobject | The name of the object to be uploaded. |
file | File | Yes | test | Document or text content does not require encoding. The browser will automatically set the Content-Type according to the file type and override your settings. TOS allows only one file to be uploaded at a time. warning When constructing a request, ensure that the file field is the last field in the form; any fields after file will be ignored. |
Cache-Control | String | No | no-cache | Default value: None |
Content-Type | String | No | image/jpeg | Default value: None |
Content-Disposition | String | No | form-data; name="key" | Default value: None |
Content-Encoding | String | No | gzip | Default value: None |
Content-Language | String | No | en-US | Default value: None |
Content-MD5 | String | No | XrY7u+Ae7tCTyyK7j1rNww== | Base64MD5 digest of the message body. |
Expires | String | No | Wed, 18 Jul 2024 18:00:00 GMT | Default value: None |
success_action_redirect | String | No | http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html | The URL to which the client is redirected after a successful upload. If this form field is not specified, the return result is determined by the success_action_status form field. If the upload fails, an error code is returned and no redirection occurs. Default value: None |
success_action_status | Integer | No | 201 | When the success_action_redirect form field is not specified, this form field specifies the status code returned to the client after a successful upload.
tip
|
x-tos-storage-class | String | No | STANDARD | Set the storage type of the object. If not specified, it will be consistent with the bucket's default storage type.
tip
|
x-tos-meta-* | String | No | x-tos-meta-tag:image | The user meta value you specified. Default value: None tip If the request contains form fields prefixed with x-tos-meta-, they are regarded as user meta, for example, x-tos-meta-location. |
x-tos-security-token | String | No | STSeyJBY2NvdW50SWQiOjIxMDAwMDUyMjQsIklkZW50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MTE3MjI5NiwiQ2hhbm5lbCI6IlVzZXIiLCJBY2Nlc3NLZXlJZCI6IkFLVFBZbUkxWkdRd01EQTBOamxoTkdGa016aGpOek0wTjJRME9UU**** | If this access uses the STS temporary authorization method, you must specify this parameter as the value of SecurityToken, and you must specify the temporary AccessKeyId that matches the SecurityToken. Default value: None |
x-tos-website-redirect-location | String | No | /anotherPage.html | When the bucket is configured with the Website setting, requests to retrieve this object can be redirected to another object within the bucket or to an external URL. TOS extracts this value from the header and stores it in the object's metadata. Default value: None |
x-tos-server-side-encryption | String | No | AES256 | Specify the encryption method for the target object. If not set, the object will be unencrypted by default. The value descriptions are as follows:
tip Using SSE-KMS for server-side encryption incurs API call fees, and creating KMS keys incurs key custody fees, both of which are charged by KMS. For more information, please refer to KMS Billing Information. |
x-tos-server-side-data-encryption | String | No | AES256 | The possible values for the encryption algorithm used with SSE-KMS encryption are explained as follows:
The default is the AES256 algorithm. |
x-tos-server-side-encryption-kms-key-id | String | No. Required when using SSE-KMS encryption. | trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test | Specify the master key to be used for SSE-KMS encryption of the target object in the following format: trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>: The TRN of the KMS master key, where region refers to the Region ID to which the key belongs, accountID refers to the ID of the account that owns the key, keyring refers to the keyring alias, and key refers to the master key alias. tip The default master key is currently not supported. If SSE-KMS encryption is specified without providing the required header, the server will return a 400 InvalidRequest error. |
x-tos-server-side-encryption-customer-algorithm | String | No; required when using SSE-C encryption. | AES256 | Specifies the algorithm to be used for SSE-C encrypted objects. The value options are explained as follows:
|
x-tos-server-side-encryption-customer-key | String | No, it is mandatory when using SSE-C encryption. | YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE= | Used in conjunction with x-tos-server-side-encryption-customer-algorithm, this parameter specifies the key for SSE-C encrypted target objects. The key must be a base64-encoded 256-bit encryption key. |
x-tos-server-side-encryption-customer-key-MD5 | String | No. Required when using SSE-C encryption. | ACdH+Fu9K3HlXdIUBu8GdA== | Used in conjunction with x-tos-server-side-encryption-customer-key, this element indicates the MD5 value of the key used to encrypt the object. This element is obtained by base64-encoding the 128-bit MD5 value of the key. It is used for message integrity verification to confirm that the encryption key has not been corrupted during transmission. |
x-tos-traffic-limit | String | No | 819200 | TOS provides single-link bandwidth throttling, enabling flow control during operations such as file upload and download to ensure network bandwidth for other applications. The explanation of values is as follows:
|
x-tos-forbid-overwrite | String | No | false | Whether overwriting an Object with the same name is permitted. The value descriptions are as follows:
tip When the target Bucket is in either versioning-enabled or versioning-suspended state, the x-tos-forbid-overwrite parameter setting is ineffective; that is, overwriting Objects with the same name is permitted. |
x-tos-object-expires | String | No | 3 | Set the expiration time for the object. After expiration, TOS will automatically delete the object. The unit is days, and only positive integers are supported. The expiration time is calculated from the object's Last-Modified time. The object will expire at the specified time, and the deletion task will be executed at midnight after the expiration time is reached. For example, set the value of the x-tos-object-expires parameter to3, if the object's Last-Modified time is 2024-09-26 12:00, the object will expire at 2024-09-30 00:00. tip
|
x-tos-object-lock-mode | String | No | COMPLIANCE | The mode of the retention policy is only COMPLIANCE, which means compliance mode. tip To set a retention policy for an object, you must first enable the retention policy feature. For detailed information, see PutBucketObjectLockConfiguration. |
x-tos-object-lock-retain-until-date | String | No | 2025-01-01T00:00:00Z | The lock expiration date of the object; within this period, the object cannot be deleted or overwritten. Follow the ISO 8601 time format. tip x-tos-object-lock-retain-until-date parameter must be used together with the x-tos-object-lock-mode parameter. |
Response headers
Name | Type | Sample value | Description |
x-tos-server-side-encryption | String | AES256 | This header field is returned when the object is encrypted using SSE-TOS or SSE-KMS. It indicates the server-side encryption method of the object, with possible values as follows:
|
x-tos-server-side-encryption-kms-key-id | String | trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test | This header field is returned when an object uses SSE-KMS encryption and indicates the KMS master key ID used for SSE-KMS encryption. |
x-tos-server-side-encryption-customer-algorithm | String | YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE= | This header field is returned when an object is encrypted using SSE-C, confirming the encryption algorithm employed. |
x-tos-server-side-encryption-customer-key-MD5 | String | ACdH+Fu9K3HlXdIUBu8GdA== | This header field is returned when an object is encrypted using SSE-C, and it indicates the MD5 value of the encryption key used. |
x-tos-version-id | String | 19EA1B32CEEB56721221 | The version number of the object. If no version number exists, this message header will not appear in the response message. |
x-tos-hash-crc64ecma | Integer | 6186290338114851376 | Represents the 64-bit CRC value of the object. The 64-bit CRC is calculated in accordance with the ECMA-182 standard. tip When server-side encryption is used for the uploaded object, this value represents the CRC64 checksum of the object's plaintext content. |
x-tos-qos-delay-time | Integer | 10 | This header field indicates the duration for which the request is subject to flow control, measured in milliseconds (ms). Upload-type requests return the exact duration for which throttling was applied, while copy-type requests or download-type requests return an estimated throttling duration based on the degree of throttling and the file size. |
Response body elements
When the value of success_action_status is set to 201, TOS will return a JSON object.
Name | Type | Sample value | Description |
Bucket | String | examplebucket | The name of the storage object's storage bucket. |
Key | String | exampleobject | Object Name. |
Location | String | https://buketname.tos-cn-beijing.volces.com/object | The URL with a domain name for the newly created object. |
ETag | String | "ab7abb0da4bca5323ab6119bb5dcd296" | Generated during the creation of each object, it uniquely identifies that object's content. |
HashCrc64ecma | String | 6186290338114851376 | CRC64 value of the uploaded file. |
Sample request
POST / HTTP/1.1
Host: examplebucket.tos-cn-beijing.volces.com
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length
--9431149156168
Content-Disposition: form-data; name="key"
exampleobject
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html
--9431149156168
Content-Disposition: form-data; name="x-tos-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="Content-Type"
image/jpg
--9431149156168
Content-Disposition: form-data; name="x-tos-server-side-encryption"
AES256
--9431149156168
Content-Disposition: form-data; name="x-tos-algorithm"
TOS4-HMAC-SHA256
--9431149156168
Content-Disposition: form-data; name="x-tos-date"
20220101T000000Z
--9431149156168
Content-Disposition: form-data; name="x-tos-credential"
testAK/20220101/cn-beijing/tos/request
--9431149156168
Content-Disposition: form-data; name="policy"
ewogICAgICAgICJleHBpcmF0aW9uIjogIjIwMjItMDEtMDVUMDA6MDA6MDAuMDAwWiIsCiAgICAgICAgImNvbmRpdGlvbnMiOiBbCiAgICAgICAgeyJidWNrZXQiOiAiZXhhbXBsZWJ1Y2tldCJ9LAogICAgICAgIFsic3RhcnRzLXdpdGgiLCAiJGtleSIsICJleGFtcGxlIl0sIAogICAgICAgIHsiYWNsIjogInB1YmxpYy1yZWFkIn0sIAogICAgICAgIHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiAiaHR0cDovL2V4YW1wbGVidWNrZXQudG9zLWNuLWJlaWppbmcudm9sY2VzLmNvbS9zdWNjZXNzZnVsX3VwbG9hZC5odG1sIn0sCiAgICAgICAgWyJzdGFydHMtd2l0aCIsICIkQ29udGVudC1UeXBlIiwgImltYWdlLyJdLCAKICAgICAgICBbInN0YXJ0cy13aXRoIiwgIiR4LXRvcy1tZXRhLXRhZyIsICIiXSwgCiAgICAgICAgCiAgICAgICAgeyJ4LXRvcy1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9LCAKICAgICAgICB7IngtdG9zLWNyZWRlbnRpYWwiOiAidGVzdEFLLzIwMjIwMTAxL2NuLWJlaWppbmcvdG9zL3JlcXVlc3QifSwgCiAgICAgICAgeyJ4LXRvcy1hbGdvcml0aG0iOiAiVE9TNC1ITUFDLVNIQTI1NiJ9LCAKICAgICAgICB7IngtdG9zLWRhdGUiOiAiMjAyMjAxMDFUMDAwMDAwWiJ9CiAgICAgICAgXQp9
--9431149156168
Content-Disposition: form-data;f name="x-tos-signature"
94d72cb3bbd094f6d8eaa0b7e56905500029813febc9fee352474f88d093c3e5
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFile.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to TOS
--9431149156168--
Sample response
HTTP/1.1 204 No Content
x-tos-id-2: 367be10900210004-a444ed0
x-tos-request-id: 367be10900210004-a444ed0
Date: Fri, 1 Jul 2022 01:00:36 GMT
Server: TosServer
Content-Length: 0
ETag: "ab7abb0da4bca5323ab6119bb5dcd296"
Location: http://examplebucket.tos-cn-beijing.volces.com/successful_upload.html
x-tos-hash-crc64ecma: 6186290338114851376
Last updated: 2025.09.30 17:38:06
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
