tencent cloud

Cloud Object Storage

Release Notes and Announcements
Release Notes
Announcements
Product Introduction
Overview
Features
Use Cases
Strengths
Concepts
Regions and Access Endpoints
Specifications and Limits
Service Regions and Service Providers
Billing
Billing Overview
Billing Method
Billable Items
Free Tier
Billing Examples
Viewing and Downloading Bill
Payment Overdue
FAQs
Getting Started
Console
Getting Started with COSBrowser
User Guide
Creating Request
Bucket
Object
Data Management
Batch Operation
Global Acceleration
Monitoring and Alarms
Operations Center
Data Processing
Content Moderation
Smart Toolbox
Data Processing Workflow
Application Integration
User Tools
Tool Overview
Installation and Configuration of Environment
COSBrowser
COSCLI (Beta)
COSCMD
COS Migration
FTP Server
Hadoop
COSDistCp
HDFS TO COS
GooseFS-Lite
Online Tools
Diagnostic Tool
Use Cases
Overview
Access Control and Permission Management
Performance Optimization
Accessing COS with AWS S3 SDK
Data Disaster Recovery and Backup
Domain Name Management Practice
Image Processing
Audio/Video Practices
Workflow
Direct Data Upload
Content Moderation
Data Security
Data Verification
Big Data Practice
COS Cost Optimization Solutions
Using COS in the Third-party Applications
Migration Guide
Migrating Local Data to COS
Migrating Data from Third-Party Cloud Storage Service to COS
Migrating Data from URL to COS
Migrating Data Within COS
Migrating Data Between HDFS and COS
Data Lake Storage
Cloud Native Datalake Storage
Metadata Accelerator
GooseFS
Data Processing
Data Processing Overview
Image Processing
Media Processing
Content Moderation
File Processing Service
File Preview
Troubleshooting
Obtaining RequestId
Slow Upload over Public Network
403 Error for COS Access
Resource Access Error
POST Object Common Exceptions
API Documentation
Introduction
Common Request Headers
Common Response Headers
Error Codes
Request Signature
Action List
Service APIs
Bucket APIs
Object APIs
Batch Operation APIs
Data Processing APIs
Job and Workflow
Content Moderation APIs
Cloud Antivirus API
SDK Documentation
SDK Overview
Preparations
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
Mini Program SDK
Error Codes
Harmony SDK
Endpoint SDK Quality Optimization
Security and Compliance
Data Disaster Recovery
Data Security
Cloud Access Management
FAQs
Popular Questions
General
Billing
Domain Name Compliance Issues
Bucket Configuration
Domain Names and CDN
Object Operations
Logging and Monitoring
Permission Management
Data Processing
Data Security
Pre-signed URL Issues
SDKs
Tools
APIs
Agreements
Service Level Agreement
Privacy Policy
Data Processing And Security Agreement
Contact Us
Glossary
DokumentasiCloud Object StorageAPI DocumentationObject APIsBasic OperationsPUT Object

PUT Object

PDF
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-03-09 15:19:58

Feature Overview

The PUT Object API request allows uploading a local object (Object) to a specified bucket. The requester must have write permissions for the bucket. If permission is denied, please refer to set access permissions. To upload to a specified bucket in the form of a web page (HTML Form), please use POST Object.


Precautions

The PUT Object Interface supports uploading files with a maximum size of 5GB. To upload files larger than 5GB, please use the Upload Part API interface.
If the Content-Length value in the request header is less than the length of the transmitted data in the actual request body, COS will still complete the file creation, but the object size will only equal the size defined in Content-Length, and other data will be discarded.
In Cloud Object Storage, there is no concept of folders and directories itself. Upload objects to a specified folder or path by using /.
Set the object key to doc/picture.png, which means uploading the picture.png object to the doc folder.
Set the object key to doc/, which means creating a folder named doc. For more details, please see folders and directories.
If you attempt to add an existing object with the same name, the newly uploaded object will override the original one, returning 200 OK upon success. To prevent overwriting previous versions, toggle on version control. For details, see version control.
Enable bucket versioning: When uploading an object, COS automatically generates a unique version ID for the added object and returns the x-cos-version-id in the response header.
Suspend bucket versioning: When uploading an object, COS always uses null as the version ID for objects in a bucket, and the response header does not return the x-cos-version-id in response.

Authorization Description

When performing authorization policy, set action to cos:PutObject, as shown in the example below.
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}
For more actions in COS, see Business APIs Supported by CAM.

Request

Request Syntax

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Content]
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com. <BucketName-APPID> indicates the bucket name with APPID suffix, for example, examplebucket-1250000000. See Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions documentation. <Region> indicates the available region for COS. See Regions and Access Endpoints documentation.
Authorization: Auth String (For details, refer to Request Signature).

Request parameters.

This API has no request parameter.

Request header.

In addition to common request headers, this API also supports the following request headers. For details on common request headers, refer to the Common Request Headers documentation.

Regular Request Header

Name
Description
Type
Required or Optional
Cache-Control
Cache directives defined in RFC 2616 will be saved as object metadata.
string
No
Content-Disposition
The file name defined in RFC 2616 will be saved as object metadata.
For example:
inline: Preview file content directly.
attachment: Download to the browser-specified path in the form of the original file name.
attachment; filename="FileName": Download to the browser-specified path in the form of a custom file name. FileName is used for customizing the downloaded file name, for example example.jpg.
string
No
Content-Encoding
The encoding format defined in RFC 2616 will be saved as object metadata.
string
No
Content-Type
The HTTP request content type (MIME) defined in RFC 2616. This header is for description of the content type of the uploaded object and will be saved as object metadata.
For example, application/xml or image/jpeg.
string
Yes
Expires
Cache expiration time defined in RFC 2616 is an absolute date and time, saved as object metadata.
string
No
Transfer-Encoding
The transfer encoding format defined in RFC 2616. If you want to use chunked transfer during upload, specify the Transfer-Encoding: chunked request header. You cannot specify the Content-Length request header.
string
No

Dedicated Request Header

When uploading an object, you can specify the following request headers to set the object's metadata, storage type, traffic control, and Tag:
Name
Description
Type
Required or Optional
x-cos-meta-[custom suffix]
Custom metadata headers. For example x-cos-meta-test: test metadata.
Note:
Custom metadata headers follow the fixed format x-cos-meta-[custom suffix]. Among them, the custom suffix supports minus signs (-), digits, and English letters (a–z). Uppercase letters in English characters will be converted to lowercase letters. Other characters, including underscores (_), are not supported.
There is no limit on the number of custom metadata headers. Each header has a size limit of 2KB, and the total size of all x-cos-meta-[custom suffix] headers must be no more than 4KB.
string
No
x-cos-storage-class
Storage type. Default value: STANDARD.
Reference values:
STANDARD
STANDARD_IA
ARCHIVE
DEEP_ARCHIVE
MAZ_STANDARD
MAZ_STANDARD_IA
MAZ_ARCHIVE
INTELLIGENT_TIERING
MAZ_INTELLIGENT_TIERING
Note:
Some storage types are only available in specific regions. Please check if the region of your current bucket applies. For details, refer to the Storage Class Overview. To specify MAZ storage type, you need to enable MAZ configuration when Creating a Bucket. To specify intelligent tiered storage type, you need to enable Overview - INTELLIGENT TIERING configuration.
enum
No
x-cos-traffic-limit
The rate-limiting value for traffic control targeting this upload must be a number, with a default unit of bit/s. The speed limit setting range is 819200 - 838860800 (800Kb/s - 800Mb/s). If outside of this range, it will return a 400 error.
integer
No
x-cos-tagging
The tag set of an object supports up to 10 tags (for example, Key1=Value1&Key2=Value2). Keys and values in the tag set must first perform URL encoding.
string
No
x-cos-forbid-overwrite
For buckets with versioning not enabled, when uploading files, used to specify whether to forbid overwriting objects with the same name during upload operation:
When the x-cos-forbid-overwrite header is not included or set to false, default overwrite applies if an Object with the same name already exists.
Set x-cos-forbid-overwrite to true to forbid overwriting an Object with the same name.
Note:
When the bucket is in enabled or paused versioning status, the x-cos-forbid-overwrite request header setting is invalid, allowing overwriting objects with the same name.
string
No

ACL Relevant Headers

When uploading an object, you can specify the following request headers to set the object's access permissions:
Name
Description
Type
Required or Optional
x-cos-acl
Define the access control list (ACL) property of the object. Default is default. For enumeration values, see the preset ACL part of the object in the ACL overview document.
Reference values:
default: inherit permissions
private: private read/write
public-read: public read/private write
Note:
If you do not need to control object ACL, set it to default or leave this item unset. Permissions are inherited from the bucket by default.
enum
No
x-cos-grant-read
Grant the read permission of the object to the authorized person. Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grant the authorized entities permission to read the object's access control list (ACL). Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grant the authorized entities permission to write to the object's access control list (ACL). Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grant all privileges on the operation object to the authorized entities. Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No

SSE-related headers

SSE can be set during object upload by specifying the server-side encryption dedicated header. Leave unset for default no encryption.

Request Body

The request body of this API request is the content of an object (file).

Response

Response Headers

In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.

Versioning-related headers

When uploading objects to a versioning-enabled bucket, the following response headers will be returned. To set version control permissions, for details, see Version Control.
Name
Description
Type
x-cos-version-id
Version ID of an object.
string

SSE-related headers

If SSE is used during object upload, this API returns headers used specifically for SSE. For details, see Server-Side Encryption Custom Header.

Response Body

The response body for this API is empty.

Case

Note:
API explorer will use frequently used and functional request headers as input parameters during use. Please check.

Error Code

This API adheres to standardized error responses and codes. For details, refer to the Error Codes document.

Appendix: PUT Object Interface SDKs for Languages

SDK
Documentation Link
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
Mini Program SDK

Topik sebelumnya: DELETE Bucket encryptionTopik selanjutnya: PUT Object - Copy

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan