Overview
This article describes how to synchronously obtain file information, such as image width, height, and format, when files are uploaded to COS.
Currently, you can store files to a COS bucket through upload APIs such as PUT Object and CompleteMultipartUploads. We provide a method for synchronously obtaining file information during upload for the following three scenarios: Scenario | File Type | Implementation Method |
Obtaining file metadata synchronously during upload | All files | ReturnBody |
Obtaining image information synchronously during upload | Image files | Method 1: ReturnBody Method 2: Pic-Operations |
Obtaining media file information synchronously during upload. | Media files | ReturnBody |
ReturnBody is a method provided by COS for obtaining file information. To obtain file information in the response, include the x-cos-return-body header and pass a custom ReturnBody parameter in your upload request (PUT Object, POST Object, or CompleteMultipartUploads). For details, refer to ReturnBody. Pic-Operations is a request header used during upload. To synchronously obtain original image information when uploading an image to COS, include this header and set the parameters for returning original image information in your upload request (PUT Object, POST Object, or CompleteMultipartUploads). For details, refer to Image Processing Mechanism Introduction. Scenario 1: Synchronously Obtaining File Metadata
To synchronously obtain file metadata after uploading a file, you can use ReturnBody. Include a ReturnBody parameter composed of the file metadata in the upload request header to obtain the file metadata in the response.
The following file metadata parameters are provided by ReturnBody:
|
bucket | The target bucket for object upload |
object | The object name used when an object is uploaded to a bucket. |
size | Object size, in bytes. |
region | The region where the bucket for object upload is located |
mimeType | Object metadata Content-Type |
To use this feature, first construct a custom ReturnBody parameter, which represents the file metadata you want to obtain in the response.
Note:
The key of the ReturnBody parameter can be customized, while the value must match the variable names provided by ReturnBody as described above.
Request Example
{
"bucket": "${bucket}",
"key": "${object}",
"filesize": "${size}",
"mime_type": "${mimeType}"
}
Then, convert the ReturnBody parameter into a string and perform URL-safe Base64 encoding to obtain: eyJidWNrZXQiOiIke2J1Y2tldH0iLCJrZXkiOiIke29iamVjdH0iLCJmaWxlc2l6ZSI6IiR7c2l6ZX0iLCJtaW1lX3R5cGUiOiIke21pbWVUeXBlfSJ9
Afterwards, to obtain the custom bucket, key, filesize, and mime_type file information in the response, include the Base64-encoded result above in the upload request by setting the x-cos-return-body header. For detailed steps, refer to ReturnBody Usage Steps. Response Example
HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
{
"bucket":"examplebucket-1250000000000",
"filesize":"30262104",
"key":"test.pptx",
"mime_type":"application/vnd.openxmlformats-officedocument.presentationml.presentation"
}
Scenario 2: Synchronously Obtaining Image Information
To synchronously obtain image information after uploading an image file, you have two implementation options: using ReturnBody or using Pic-Operations. The obtained image information can then be used for subsequent processing, such as image classification and tagging.
Note:
Both implementation methods rely on the capabilities of the CI (Cloud Infinite) service. Before use, you must first activate CI and bind a bucket. For details, refer to Bucket Operations. Basic Image Processing fees are charged by the CI service for obtaining image information. For details, refer to Image Processing Fees. Method 1: Synchronously Obtaining Image Information via ReturnBody
To obtain image information synchronously via ReturnBody, include a ReturnBody parameter composed of the image metadata in the upload request header. You can then obtain the image information from the response.
Note:
Currently, this feature is only supported for use in public cloud regions within the Chinese mainland.
The image information provided by ReturnBody includes: basic image information (imageInfo) and image exif information.
Among them, the basic image information (imageInfo) includes:
|
imageInfo.format | Image type, such as png, gif, and so on |
imageInfo.width | Image width, measured in pixels (px). |
imageInfo.height | Image height, measured in pixels (px). |
imageInfo.size | Image size, measured in Bytes. |
imageInfo.md5 | md5 value of the image. |
imageInfo.frame_count | Number of image frames. A static image has 1 frame, while an animated image has the corresponding number of frames. |
imageInfo.bit_depth | Bit depth of the image. |
imageInfo.vertical_dpi | Vertical DPI of the image. |
imageInfo.horizontal_dpi | Horizontal DPI of the image. |
Image exif information primarily records hardware or software details from the shooting process and includes, but is not limited to, the following items:
|
exif.ColorSpace.val | Color gamut, color space |
exif.DateTime.val | Creation time. |
exif.Orientation.val | Direction |
exif.ResolutionUnit.val | Resolution unit |
exif.XResolution.val | X-direction resolution |
exif.YResolution.val | Y-direction resolution |
... | ... |
When using this feature, you must still first customize the ReturnBody parameter based on the image information provided by ReturnBody. To prevent excessive content in ReturnBody from affecting API performance, directly specifying ${imageInfo} or ${exif} is not supported. You must explicitly specify the specific sub-variables, for example, ${variableName.subVariable} or ${variableName.secondLevelSubVariable}.
Note:
The key of the ReturnBody parameter can be customized, while the value must match the variable names provided by ReturnBody as described above.
Request Example
{
"color_space": "${exif.ColorSpace.val}",
"format": "${imageInfo.format}",
"width": "${imageInfo.width}",
"height": "${imageInfo.height}",
"md5": "${imageInfo.md5}",
"bit_depth": "${imageInfo.bit_depth}",
"vertical_dpi": "${imageInfo.vertical_dpi}",
"horizontal_dpi": "${imageInfo.horizontal_dpi}"
}
Then, convert the ReturnBody parameter into a string and perform URL-safe Base64 encoding to obtain: eyJjb2xvcl9zcGFjZSI6IiR7ZXhpZi5Db2xvclNwYWNlLnZhbH0iLCJmb3JtYXQiOiIke2ltYWdlSW5mby5mb3JtYXR9Iiwid2lkdGgiOiIke2ltYWdlSW5mby53aWR0aH0iLCJoZWlnaHQiOiIke2ltYWdlSW5mby5oZWlnaHR9IiwibWQ1IjoiJHtpbWFnZUluZm8ubWQ1fSIsImJpdF9kZXB0aCI6IiR7aW1hZ2VJbmZvLmJpdF9kZXB0aH0iLCJ2ZXJ0aWNhbF9kcGkiOiIke2ltYWdlSW5mby52ZXJ0aWNhbF9kcGl9IiwiaG9yaXpvbnRhbF9kcGkiOiIke2ltYWdlSW5mby5ob3Jpem9udGFsX2RwaX0ifQ
To obtain custom image information such as color_space, format, width, and height in the response, include the Base64-encoded result above in the upload request by setting the x-cos-return-body header. For detailed steps, refer to ReturnBody Usage Steps. Response Example
HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
{
"bit_depth":"8",
"color_space":"sRGB",
"format":"png",
"height":"800",
"horizontal_dpi":"0",
"md5":"4f5c260f63af3c56cea542a1c62a0a1b",
"vertical_dpi":"0",
"width":"1200"
}
Method 2: Synchronously Obtaining Image Information via Pic-Operations
To synchronously obtain original image information via Pic-Operations, simply add the Pic-Operations item to the request header and set the parameters for returning original image information. You can then obtain the original image information synchronously after the image is uploaded to COS. For details, refer to Image Processing Mechanism Introduction. When uploading an image via putObject, set Pic-Operations in the request header and set is_pic_info to 1 to indicate that original image information should be returned. You can then obtain the original image information from the request result.
Example Requests
PUT /filename.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Tue, 04 Apr 2023 09:06:15 GMT
Authorization:XXXXXXXXXXXX
Pic-Operations: {"is_pic_info":1}
Content-Length: 64
[Object]
Response Example
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 04 Apr 2023 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****
<UploadResult>
<OriginalInfo>
<Key>filename.jpg</Key>
<Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
<ETag>"580cd6930444576523c25f86ce2af9b1fc2d5484"</ETag>
<ImageInfo>
<Format>JPEG</Format>
<Width>640</Width>
<Height>427</Height>
<Quality>100</Quality>
<Ave>0xa18454</Ave>
<Orientation>1</Orientation>
<FrameCount>1</FrameCount>
</ImageInfo>
</OriginalInfo>
</UploadResult>
Note:
Pic-Operations supports synchronously obtaining image information during COS V5 multipart uploads. When using the COS V5 Complete Multipart Upload API, simply include the Pic-Operations item in the request header. After the multipart upload is completed, you can obtain the image information from the request result. Pic-Operations can only be used in regions supported by CI. For details, see Regions and Domains. Only images smaller than 32 MB are supported.
Scenario 3: Synchronously Obtaining Media File Information
Note:
Synchronously obtaining media file information via ReturnBody depends on the MPS feature of the CI service. Before use, you must first activate CI, bind a bucket (see Bucket Operations), and enable the MPS feature. CI charges a fee for obtaining video metadata. For details, see MPS Fees. To synchronously obtain media file information after uploading a media file, you can use ReturnBody. Include a ReturnBody parameter composed of the media file information in the upload request header to obtain the media file information in the response.
Note:
Currently, this feature is only supported for use in public cloud regions within the Chinese mainland.
The main media file information provided by ReturnBody can be referenced in the table below. For more details, see Media File Information. |
videoInfo.video.bit_rate | Video bit rate, in kbps |
videoInfo.video.codec_name | Video codec format name |
videoInfo.video.profile | Video encoding profile |
videoInfo.video.pix_fmt | Pixel format |
videoInfo.audio.bit_rate | Audio bit rate, in kbps |
videoInfo.audio.codec_name | Audio codec format name |
videoInfo.format.duration | Duration, in seconds |
... | ... |
When using this feature, you must still first customize the ReturnBody parameter based on the media file information provided by ReturnBody. To prevent excessive content in ReturnBody from affecting API performance, directly specifying ${videoInfo} is not supported. You must explicitly specify the specific sub-variables, for example, ${variableName.subVariable} or ${variableName.secondLevelSubVariable}.
Note:
The key of the ReturnBody parameter can be customized, while the value must match the variable names provided by ReturnBody as described above.
Request Example
{
"video_bit_rate": "${videoInfo.video.bit_rate}",
"video_codec_name": "${videoInfo.video.codec_name}",
"video_profile": "${videoInfo.video.profile}",
"video_pix_fmt": "${videoInfo.video.pix_fmt}",
"audio_bit_rate": "${videoInfo.audio.bit_rate}",
"audio_codec_name": "${videoInfo.audio.codec_name}",
"duration": "${videoInfo.format.duration}",
}
Then, convert the ReturnBody parameter into a string and perform URL-safe Base64 encoding to obtain: eyJ2aWRlb19iaXRfcmF0ZSI6IiR7dmlkZW9JbmZvLnZpZGVvLmJpdF9yYXRlfSIsInZpZGVvX2NvZGVjX25hbWUiOiIke3ZpZGVvSW5mby52aWRlby5jb2RlY19uYW1lfSIsInZpZGVvX3Byb2ZpbGUiOiIke3ZpZGVvSW5mby52aWRlby5wcm9maWxlfSIsInZpZGVvX3BpeF9mbXQiOiIke3ZpZGVvSW5mby52aWRlby5waXhfZm10fSIsImF1ZGlvX2JpdF9yYXRlIjoiJHt2aWRlb0luZm8uYXVkaW8uYml0X3JhdGV9IiwiYXVkaW9fY29kZWNfbmFtZSI6IiR7dmlkZW9JbmZvLmF1ZGlvLmNvZGVjX25hbWV9IiwiZHVyYXRpb24iOiIke3ZpZGVvSW5mby5mb3JtYXQuZHVyYXRpb259In0
To obtain custom media file information such as video_bit_rate, video_codec_name, and video_profile in the response, include the Base64-encoded result above in the upload request by setting the x-cos-return-body header. For detailed steps, refer to ReturnBody Usage Steps. Response Example
HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****
{
"audio_bit_rate":"189.375000",
"audio_codec_name":"aac",
"duration":"123.875000",
"video_bit_rate":"2936.675000",
"video_codec_name":"h264",
"video_pix_fmt":"yuv420p",
"video_profile":"Main"
}