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

ReturnBody

PDF

Focus Mode

Font Size

Last updated: 2025-11-28 17:42:56

Users can obtain information about the object in the response by including the ReturnBody parameter in upload requests (PUT Object, POST Object, CompleteMultipartUpload).
System Variable
The supported system variables for the upload callback ReturnBody are listed in the following table:
Note:
Obtaining exif, videoinfo, and imageinfo information depends on the capabilities of the CI (Cloud Infinite, CI) service. Obtaining these three types of variables will incur corresponding fees from the CI service; for details, refer to the CI Billing Overview.
Variable Name
Variable Description
Whether Sub-Variables Are Included
Required or Not
bucket
The target bucket for object upload.
No
No
object
The object name used for uploading the object to the bucket.
No
No
size
Object size, in bytes.
No
No
region
The region of the bucket for object upload.
No
No
mimeType
Object metadata Content-Type.
No
No
exif
If the uploaded object is an image type, it supports viewing the image's exif information, and the variable format is ${exif.sub-variable}.
Note:
To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in ${exif}; it is advised to specify the specific sub-variables.
Yes
No
videoInfo
If the uploaded object is an audio or video type, it supports viewing the metadata of the audio and video resources. The variable format is ${videoInfo.sub-variable}.
Note:
To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in ${videoInfo}; it is advised to specify the specific sub-information items.
Yes
No
imageInfo
If the uploaded object is an image type, it supports viewing the basic information of the image. The variable format is ${imageInfo.sub-variable}.
Note:
To avoid ReturnBody carrying excessive content and affecting interface performance, it is not recommended to directly fill in ${imageInfo}; it is advised to specify the specific sub-variables.
Yes
No
When using the exif, imageInfo, videoInfo variables, note the following points:
These three types of variables are only supported in domestic public cloud regions.
Obtaining these three types of variables depends on the capabilities of the CI (Cloud Infinite, CI) service. Users need to activate the CI service and ensure that the COS service role has the permission to invoke the CI service. Obtaining these three types of variables will incur corresponding fees from the CI service. For details, refer to CI billing overview.
Sub-variables are supported, such as ${variableName.sub-variable} and ${variableName.second-level-sub-variable}. To avoid ReturnBody carrying excessive content and affecting interface performance, it is not recommended to directly fill in ${imageInfo}; it is advised to specify the specific sub-variables.
For the specific sub-variables supported by variables, refer to the product documentation of CI and MPS services.
Note:
The exif and imageInfo variables only support image files, while videoInfo only supports audio and video files. A format mismatch will cause the callback to fail (Error Code 203).
exif: Obtain image EXIF
imageInfo: Obtain basic image information
videoInfo: Obtain media information
Procedure
Step One: Construct the ReturnBody Parameter
1. Express the desired object information in json format. In the sample below, bucket, key, myfilesize, and height are user-defined parameter names. Variable names are wrapped in ${}, and the values corresponding to these variable names represent the callback information to be obtained. For supported variable names in ReturnBody, refer to System Variables above. Sample:
# Example of Obtaining Image Information
{
    "bucket": "${bucket}",
    "key": "${object}",
    "myfilesize": "${size}",
    "height": "${imageInfo.height}"
}
﻿
# Sample for Obtaining Video Information Refer to the response content when magicvar = 1 in Obtain media information
{
    "bucket":"${bucket}",
    "key":"${object}",
    "myfilesize":"${size}",
    "video_duration":"${videoInfo.format.duration}",
    "video_bitrate":"${videoInfo.format.bit_rate}"
}
﻿
2. Convert the above json format to a string and Base64-encode it.
# Example of Obtaining Image Information
eyJidWNrZXQiOiAiJHtidWNrZXR9IiwgImtleSI6ICIke29iamVjdH0iLCAibXlmaWxlc2l6ZSI6ICIke3NpemV9IiwgImhlaWdodCI6ICIke2ltYWdlSW5mby5oZWlnaHR9In0=
﻿
# Example of Obtaining Video Information
ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9
Step 2: Include the ReturnBody Parameter in the Upload Object Request
1. In the PUT Object request, pass the Base64-encoded result via the request header x-cos-return-body. The request example is as follows:
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
x-cos-return-body: eyJidWNrZXQiOiAiJHtidWNrZXR9IiwgImtleSI6ICIke29iamVjdH0iLCAibXlmaWxlc2l6ZSI6ICIke3NpemV9IiwgImhlaWdodCI6ICIke2ltYWdlSW5mby5oZWlnaHR9In0=
Authorization: Auth String
﻿
[Object Content]
2. In the POST Object request, pass the Base64-encoded result via the form field x-cos-return-body.
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:34 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Length: 1119
Connection: close
﻿
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-sign-algorithm"
﻿
sha1
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-ak"
﻿
AKIDLdDGwRp0KIuI9sZDeJG3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-key-time"
﻿
1759216346;1759217246
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-signature"
﻿
71f6d4a559axxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="policy"
﻿
eyJleHBpcmF0aW9uIjoiMjAyNS0wOS0zMFQwNzoyNzoyNi4wMDBaIiwiY29uZGl0aW9ucyI6W3sicS1zaWduLWFsZ29yaXRobSI6InNoYTEifSx7InEtYWsiOiJBS0lETGRER3dScDBLSXVJOXNaRGVKRzN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHgifSx7InEtc2lnbi10aW1lIjoiMTc1OTIxNjM0NjsxNzU5MjE3MjQ2In0seyJidWNrZXQiOiJleGFtcGxlYnVja2V0LTEyNTAwMDAwMDAifSx7ImtleSI6ImV4YW1wbGVvYmplY3QifV19
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="x-cos-security-token"
﻿
ZflOqzkNb2266djz4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="key"
﻿
exampleobject
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="x-cos-return-body"
﻿
ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="file"; filename="example.mp4"
Content-Type: video/mp4
﻿
[Object Content]
------WebKitFormBoundaryZBPbaoYE2gqeB21N--
3. In the Complete Multipart Upload request, pass the Base64-encoded result via the request header x-cos-return-body.
POST /exampleobject?uploadId=UploadId HTTP/1.1
Host: exmaplebucket-1250000000.cos.region.myqcloud.com
x-cos-return-body: ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String
﻿
[Request Body]
Step 3: Obtain the ReturnBody Information in the Response
1. The return of PUT Object will return object information in the response body in json format. The response example is as follows:
HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
﻿
{
 "bucket": "examplebucket-1250000000000",
 "height": "887",
 "key": "test.jpeg",
 "myfilesize": "214513"
}
2. The return of POST Object will return object information in the response body in json format. The response example is as follows:
HTTP/1.1 201 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
﻿
{
 "bucket": "examplebucket-1250000000000",
 "key": "test.mp4",
 "myfilesize": "214513",
 "video_duration": 1000,
 "video_bitrate": 1000
}
3. The Complete Multipart Upload request itself returns an XML request body, which contains important information about the multipart upload. Therefore, the ReturnBody-related information (object information, whether the ReturnBody calculation is successful, etc.) will be placed in the XML field ReturnBodyResult and returned to the user.
The ReturnBodyResult node is described below:
Node Name (Keyword)
Parent Node
Description
Type
ReturnBodyResult
CompleteMultipartUploadResult
ReturnBody's result information.
Container
Status
CompleteMultipartUploadResult.ReturnBodyResult
Whether the ReturnBody is obtained successfully. Supported enum values: 200, 203.
200 indicates a successful upload and successful obtainment of ReturnBody;
203 indicates a successful upload but failure to obtain ReturnBody.
Integer
Error
CompleteMultipartUploadResult.ReturnBodyResult
When the Status is 203, it indicates that the ReturnBody failed to be obtained. An Error is returned, providing the callback failure information.
Container
Code
CompleteMultipartUploadResult.ReturnBodyResult
The error code for callback failure information, such as GetReturnBodyFailed.
String
Message
CompleteMultipartUploadResult.ReturnBodyResult
The error message for a failed obtainment of ReturnBody.
String
ReturnBody
CompleteMultipartUploadResult.ReturnBodyResult
When the Status is 200, it indicates a successful upload and callback. The ReturnBody is returned, which is a Base64-encoded string of the ReturnBody json.
String
Response example:
HTTP/1.1 200 OK
Content-Type: application/xml
﻿
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>"aa259a62513358f69e98e******"</ETag>
    <ReturnBodyResult>
        <Status>200|203</Status>
        <!--When the Status is 203, it indicates that ReturnBody failed, and an Error is returned-->
        <Error>
            <Code>GetReturnBodyFailed</Code>
            <Message>Invalid return body params.</Message>
        </Error>
        <!--When the Status is 200, it indicates a successful upload and successful computation of ReturnBody. The Base64-encoded result of the json string is returned.-->
        <ReturnBody>
            eyJhIjogImIifQ==
        </ReturnBody>
    </ReturnBodyResult>
</CompleteMultipartUploadResult>
Return code
After the ReturnBody parameter is used in an upload request, the return codes mainly fall into the following cases:
A successful upload request and successful obtainment of ReturnBody, and 200 is returned.
Upload request succeeded, but failed to obtain ReturnBody:
Failure reason
Return code
ErrorCode
Message
The ReturnBody parameter is invalid.
203
GetReturnBodyFailed
Invalid return body params.
Calling the CI service results in a failure to obtain parameters due to reasons such as lack of access permissions or unactivated services.
203
GetReturnBodyFailed
Error status from ci: ${code}, should return 200 OK.
Here, ${code} is the error code returned by the data service, such as 400, 403, etc.
Upload failed. ReturnBody computation will not be triggered, and the returned error codes and messages follow the rules of regular upload requests.
Best Practices
For details, see How to Return File Information in Upload Request Responses.

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

Cloud Object Storage

ReturnBody

System Variable

Procedure

Step One: Construct the ReturnBody Parameter

Step 2: Include the ReturnBody Parameter in the Upload Object Request

Step 3: Obtain the ReturnBody Information in the Response

Return code

Best Practices

Help and Support

Variable Name	Variable Description	Whether Sub-Variables Are Included	Required or Not
bucket	The target bucket for object upload.	No	No
object	The object name used for uploading the object to the bucket.	No	No
size	Object size, in bytes.	No	No
region	The region of the bucket for object upload.	No	No
mimeType	Object metadata Content-Type.	No	No
exif	If the uploaded object is an image type, it supports viewing the image's exif information, and the variable format is `${exif.sub-variable}`. Note: To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in `${exif}`; it is advised to specify the specific sub-variables.	Yes	No
videoInfo	If the uploaded object is an audio or video type, it supports viewing the metadata of the audio and video resources. The variable format is `${videoInfo.sub-variable}`. Note: To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in `${videoInfo}`; it is advised to specify the specific sub-information items.	Yes	No
imageInfo	If the uploaded object is an image type, it supports viewing the basic information of the image. The variable format is `${imageInfo.sub-variable}`. Note: To avoid ReturnBody carrying excessive content and affecting interface performance, it is not recommended to directly fill in `${imageInfo}`; it is advised to specify the specific sub-variables.	Yes	No

Node Name (Keyword)	Parent Node	Description	Type
ReturnBodyResult	CompleteMultipartUploadResult	ReturnBody's result information.	Container
Status	CompleteMultipartUploadResult.ReturnBodyResult	Whether the ReturnBody is obtained successfully. Supported enum values: 200, 203. 200 indicates a successful upload and successful obtainment of ReturnBody; 203 indicates a successful upload but failure to obtain ReturnBody.	Integer
Error	CompleteMultipartUploadResult.ReturnBodyResult	When the Status is 203, it indicates that the ReturnBody failed to be obtained. An Error is returned, providing the callback failure information.	Container
Code	CompleteMultipartUploadResult.ReturnBodyResult	The error code for callback failure information, such as GetReturnBodyFailed.	String
Message	CompleteMultipartUploadResult.ReturnBodyResult	The error message for a failed obtainment of ReturnBody.	String
ReturnBody	CompleteMultipartUploadResult.ReturnBodyResult	When the Status is 200, it indicates a successful upload and callback. The ReturnBody is returned, which is a Base64-encoded string of the ReturnBody json.	String

Failure reason	Return code	ErrorCode	Message
The ReturnBody parameter is invalid.	203	GetReturnBodyFailed	Invalid return body params.
Calling the CI service results in a failure to obtain parameters due to reasons such as lack of access permissions or unactivated services.	203	GetReturnBodyFailed	Error status from ci: ${code}, should return 200 OK. Here, `${code}` is the error code returned by the data service, such as 400, 403, etc.