Function Description

This interface is used to perform object copy operations within the same bucket or between different buckets in the same region.

All replication requests must be authenticated. In addition, you must have read access to the source object and write access to the target bucket. When copying an object, you can retain all metadata (default) or specify new metadata. However, the ACL is not retained; instead, it is set to private for the user making the request. To override the default ACL settings, specify a new ACL when generating the copy request.

When a bucket is configured for multi-versioning, if you need to restore an earlier version of an object as the current version, simply copy the earlier version of the object into the same bucket. TOS will set the corresponding earlier version of the object as the current version.

Server-Side Encryption

When performing the CopyObject operation, you can choose to use server-side encryption-related headers, such as using TOS-managed keys (SSE-TOS), customer-provided encryption keys (SSE-C), or KMS-managed keys (SSE-KMS) for server-side encryption. With server-side encryption, TOS encrypts your uploaded data at the file level upon receipt and then stores the encrypted data persistently. When you download a file, TOS automatically decrypts the data and returns it to you. For more detailed information about server-side encryption, please refer to the Server-Side Encryption Overview.

Usage Restrictions

The limitations of Object when using the CopyObject interface are as follows:

The valid size range for the target object is [0, 5GiB]. If the source object size exceeds 5GiB, please use the UploadPartCopy interface.

Both the CopyObject and UploadPartCopy interfaces require read permission on the source Object.

Before using the CopyObject API to copy objects in Archive Storage, Cold Archive Storage, or Deep Cold Archive Storage, you must first restore the objects.

Billing Instructions

Invoking the CopyObject API is equivalent to performing a GET Object operation on the source bucket and a PUT Object operation on the destination bucket. As a result, the source bucket will incur an additional read request fee, and the destination bucket will incur an additional write request count fee. For detailed billing information, please refer to Request Count Charges.

After invoking the CopyObject API, the target bucket will increase its storage capacity accordingly.

When you call the CopyObject interface to change the storage type of an object, data overwriting may be involved. For example, if you call the CopyObject API to change a low-frequency storage object with a 15-day retention period to standard storage, a capacity fee will be incurred for the low-frequency storage period that is less than the required minimum duration. For detailed billing information, please refer to Storage Capacity Fees.

Request syntax

Request parameters and headers

Name	Location	Type	Required	Sample Value	Description
x-tos-acl	Header	String	No	private	Access permissions for the target object. Effective permission settings include: private: Private; default value. public-read: public read access. public-read-write: public read/write. authenticated-read: Read by authenticated users. bucket-owner-read: Bucket owner read. bucket-owner-full-control: Full control for the bucket owner. bucket-owner-entrusted: Subject to bucket policy control; the bucket owner has full permissions. default: Inherit the bucket ACL, meaning the object's ACL policy is consistent with the bucket ACL policy.
x-tos-copy-source	Header	String	Yes	/sourcebucketname/SourceObjectName?versionId=xxx	Specify the source bucket and source object name for the copy operation. The source object name must be URL encoded in accordance with the application/x-www-form-urlencoded standard. When the source object has multiple versions, specify the version number of the source object using versionId.
x-tos-copy-source-if-match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The copy object operation is performed only when the ETag of the source object is equal to the value specified by this parameter.
x-tos-copy-source-if-modified-since	Header	String	No	Mon, 04 Jul 2022 02:57:31 GMT	If the object has been modified since the specified time, copy the object. The time format is RFC1123 GMT.
x-tos-copy-source-if-none-match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The object copy operation is performed only when the ETag of the source object does not equal the value specified by this parameter.
x-tos-copy-source-if-unmodified-since	Header	String	No	Mon, 04 Jul 2022 02:57:31 GMT	If the object has not been modified since the specified time, copy the object. The time format is RFC1123 GMT.
x-tos-server-side-encryption	Header	String	No	AES256	Specify the encryption method for the target object. If not configured, the object is not encrypted by default. The possible values are explained as follows: AES256: Uses SSE-TOS encryption and the AES256 encryption algorithm. SM4: Uses SSE-TOS encryption and adopts the SM4 encryption algorithm. kms: Uses SSE-KMS encryption. For a detailed explanation of the SSE-TOS and SSE-KMS encryption methods, see Server-Side Encryption Overview. 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	Header	String	No	AES256	The possible values for the encryption algorithm used with the SSE-KMS encryption method are explained as follows: AES256: AES256 encryption algorithm. SM4: SM4 encryption algorithm. The default is the AES256 algorithm.
x-tos-server-side-encryption-kms-key-id	Header	String	No, it is required when using SSE-KMS encryption.	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	Specify the master key used by SSE-KMS to encrypt the target object, in the following format: trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>: The TRN of the KMS master key. region is the Region ID to which the key belongs. accountID is the ID of the account to which the key belongs. keyring is the keyring alias. key is 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	Header	String	No. Required when using SSE-C encryption.	AES256	Specify the algorithm to be used for SSE-C encryption of the target object. The value options are as follows: AES256: Encrypts objects using the AES256 algorithm. For detailed information, see Server-Side Encryption.
x-tos-server-side-encryption-customer-key	Header	String	No. Required when using SSE-C encryption.	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=	When used in conjunction with x-tos-server-side-encryption-customer-algorithm, you can specify the key for SSE-C encryption of the target object. The key is a 256-bit encryption key encoded in base64.
x-tos-server-side-encryption-customer-key-MD5	Header	String	No; mandatory when using SSE-C encryption.	0gYVWExOAz67jX5A6qY4+A==	Used in conjunction with x-tos-server-side-encryption-customer-key, this header field indicates the MD5 value of the key used to encrypt the target object. This header field is obtained by base64 encoding the 128-bit MD5 value of the key. This value is used for message integrity verification to ensure that the encryption key has not been corrupted during transmission.
x-tos-copy-source-server-side-encryption-customer-algorithm	Header	String	No, when the source object is encrypted with SSE-C, it is required.	AES256	This header field is used when the source object is encrypted with SSE-C. It specifies the algorithm used to decrypt the source object. The possible values are described as follows: AES256: SSE-TOS encryption method. For detailed information, see Server-Side Encryption.
x-tos-copy-source-server-side-encryption-customer-key	Header	String	No. When the source object is encrypted with SSE-C, it is required.	1234567890abcdefghijklmnopqrstuv	This header field is used during SSE-C encryption to decrypt the source object. The encryption key provided in this header field must be the key used when creating the source object.
x-tos-copy-source-server-side-encryption-customer-key-MD5	Header	String	No. When the source object uses SSE-C encryption, it is required.	0gYVWExOAz67jX5A6qY4+A==	This header field is used during SSE-C encryption of the source object, in conjunction with x-tos-copy-source-server-side-encryption-customer-key. It specifies the MD5 value of the key used to decrypt the source object. This header field is generated by base64-encoding the 128-bit MD5 value of the key. The resulting value is used for message integrity verification to ensure that the encryption key has not been corrupted during transmission.
x-tos-grant-full-control	Header	String	No	id=123,id=456	Use this header field to grant the grantee permissions for the object, including READ, READ ACP, and WRITE ACP. Format: id=account1,id=account2.
x-tos-grant-read	Header	String	No	id=123,id=456	Permission that allows authorized users to read objects and object metadata. Format: id=account1,id=account2.
x-tos-grant-read-acp	Header	String	No	id=123,id=456	Allow authorized users to read the object's ACL. Format: id=account1,id=account2.
x-tos-grant-write-acp	Header	String	No	id=123,id=456	Authorized users are permitted to modify the object ACL. Format: id=account1,id=account2.
x-tos-metadata-directive	Header	String	No	COPY	Specifies whether to copy metadata from the source object or to replace the metadata with that provided in the request. The explanation of values is as follows: COPY: Copies metadata from the source object; this is the default value. REPLACE: Replace using the metadata provided in the request.
x-tos-meta-*	Header	String	No	x-tos-meta-key: value	When x-tos-metadata-directive is set to REPLACE, you can include headers beginning with x-tos-meta- in the HTTP request to add custom metadata.
x-tos-website-redirect-location	Header	String	No	/anotherObjectName	When the bucket is configured with a 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.
x-tos-storage-class	Header	String	No	STANDARD	Set the storage type of the target object. If not specified, the storage class of the target object will be consistent with the default storage class of the bucket. The value options are as follows: STANDARD: Standard storage. IA: Infrequent access storage. INTELLIGENT_TIERING: Intelligent tiered storage. ARCHIVE_FR: Flashback archive storage. ARCHIVE: Archive storage. COLD_ARCHIVE: Cold archive storage. DEEP_COLD_ARCHIVE: Deep cold archive storage. tip Currently, only China(Beijing), China (Shanghai), and China (Guangzhou) support cold archive storage. Currently, only China (Beijing), China (Shanghai), and China (Guangzhou) support deep cold archive storage, and all are in invitation-only testing. If you require this storage type, please contact your account manager.
x-tos-tagging	Header	String	No	Key1=Value1&Key2=Value2	Set the object's tag information in the format {Key&Separation. tip The Key and Value of object tags must be URL encoded first. If an object is not used=If Value is set, TOS will treat the Value of this tag as an empty string. For more information on restrictions related to object tags, see Object Tags.
x-tos-tagging-directive	Header	String	No	Copy	Handling method for object tags when configuring object replication. The possible values are explained as follows: Copy (default): Copies the tag information of the source object. Replace: The tag information of the source object is not copied; instead, the tags carried in the request are used directly.
x-tos-traffic-limit	Header	String	No	819200	TOS provides single-link speed limiting functionality, enabling flow control during file upload, download, and other operations to ensure network bandwidth for other applications. The explanation of values is as follows: Value range: 245760–838860800, unit: bit/s. This parameter cannot exist simultaneously in both the Header and Query.
x-tos-forbid-overwrite	Header	String	No	false	Is overwriting an Object with the same name permitted? Value description is as follows: If not specified or specified as false, overwriting Objects with the same name is allowed. When set to true: it means overwriting Objects with the same name is prohibited. tip When the target Bucket is in a versioning-enabled or versioning-suspended state, the x-tos-forbid-overwrite parameter setting is ineffective, and overwriting Objects with the same name is permitted.
x-tos-traffic-limit	Query	String	No	819200	TOS provides single-link bandwidth throttling, enabling flow control during file upload, download, and similar operations to ensure network bandwidth for other applications. The explanation of values is as follows: Value range: 245760–838860800; unit: bit/s. This parameter cannot exist simultaneously in both the Header and Query.
x-tos-object-expires	Header	String	No	3	Set the expiration time for the object. After expiration, TOS will automatically delete the object. The unit is days and can be set as a positive integer, indicating that the object will expire at the specified time. The expiration period is calculated from the object's Last-Modified 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 to3If the object's Last-Modified time is 2024-09-26 12:00, the object will expire at 2024-09-30 00:00. tip By default, the expiration time of the source object is not inherited. The object expiration time takes precedence over lifecycle deletion rules. For example, if the object expiration time is set to 5 days and the lifecycle rule specifies deletion after 3 days, the object will ultimately be deleted according to the expiration time, that is, after 5 days.
x-tos-object-lock-mode	Header	String	No	COMPLIANCE	The mode of the retention policy can only be set to COMPLIANCE, indicating compliance mode. tip To configure 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	Header	String	No	2025-01-01T00:00:00Z	Until the lock expiration date, 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.
if-match	Header	String	No	d41d8cd98f00b204e9800998ecf8427e	The ETag condition that controls upload behavior ensures that an object is uploaded only when the specified ETag matches the ETag of an existing object in the bucket. If the specified ETag does not exist or does not match, the object upload will fail and a 412 status code will be returned.
if-none-match	Header	String	No	d41d8cd98f00b204e9800998ecf8427e	The ETag condition that governs upload behavior ensures that an object is uploaded only when the specified ETag does not match the ETag of an existing object in the bucket. If an existing object's ETag in the storage bucket matches the specified ETag, the upload will fail and a 412 status code will be returned. tip if-none-match supports being set to*This means that if an object with the same name exists in the target bucket, regardless of its ETag, the upload will fail and a 412 status code will be returned.

Request body elements

This request does not use a message element.

Response headers

For the public response message headers returned by this request, see Public Parameters.

Name	Type	Sample value	Description
x-tos-copy-source-version-id	String	57AF1A32CECB56721267	The version number of the source object, returned when copying a specified object version.
x-tos-version-id	String	43D62700044343044833	Version number of the target object.
x-tos-server-side-encryption	String	kms	This header field indicates the server-side encryption method of the object. It is returned when the object is encrypted using SSE-TOS or SSE-KMS. The possible values are as follows: AES256: Uses the SSE-TOS encryption method and employs the AES256 encryption algorithm. SM4: Uses SSE-TOS encryption and adopts the SM4 encryption algorithm. kms: Use the SSE-KMS encryption method. For a detailed explanation of the SSE-TOS and SSE-KMS encryption methods, please refer to the Server-Side Encryption Overview.
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	This header field indicates the KMS master key ID used for SSE-KMS encryption. This header field is returned when the object uses SSE-KMS encryption.
x-tos-server-side-encryption-customer-algorithm	String	AES256	This header field specifies the encryption algorithm used for SSE-C encryption and is returned when the target object is encrypted using SSE-C.
x-tos-server-side-encryption-customer-key-md5	String	0gYVWExOAz67jX5A6qY4+A==	This header field indicates the MD5 value of the key used for SSE-C encryption and is returned when the target object is encrypted using SSE-C.
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 requests return the exact duration affected by rate limiting; copy requests or download requests return an estimated duration affected by rate limiting, based on the degree of rate limiting and the file size.

Response body elements

Name	Type	Sample value	Description
ETag	String	8a36be0d764367db4eea2deb16b71543	The ETag value of the target object.
LastModified	String	2021-08-20T06:38:52.000Z	Last modification time of the target object.

Sample request

Sample response

Torch Object Storage