Object Storage Service:Image label detection

Feature description

Image label detection identifies content such as scenes, objects, and events in images to enable automatic image tagging. This feature supports thousands of labels across more than 30 categories, as shown in the following figure.

Scenarios

Precautions

• Image label detection supports only images in JPG, PNG, or JPEG format.

• The following limits apply to image size:

  • The image size cannot exceed 20 MB.

  • The image height or width cannot exceed 30,000 pixels (px).

  • The total number of pixels in the image cannot exceed 250 million.

• Image label detection supports only synchronous processing (using the x-oss-process method).

• Anonymous access will be denied.

How to use

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.OSSObject;
import com.aliyun.oss.model.GetObjectRequest;
import com.aliyuncs.exceptions.ClientException;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

public class Demo {
    public static void main(String[] args) throws ClientException, ClientException {
        // Set yourEndpoint to the endpoint of the region where the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region corresponding to the endpoint, for example, cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // If the image is in the root directory of the bucket, specify the image name. If the image is not in the root directory, specify the full path, for example, exampledir/example.jpg.
        String key = "example.jpg";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer needed, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Construct the processing instruction for image label detection.
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
            getObjectRequest.setProcess("image/labels");

            // Use the getObject method and pass the processing instruction through the process parameter.
            OSSObject ossObject = ossClient.getObject(getObjectRequest);

            // Read and print the information.
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = ossObject.getObjectContent().read(buffer)) != -1) {
                baos.write(buffer, 0, bytesRead);
            }
            String imageLabels = baos.toString("UTF-8");
            System.out.println("Image Labels:");
            System.out.println(imageLabels);
        } catch (IOException e) {
            System.out.println("Error: " + e.getMessage());
        } finally {
            // Shut down the OSSClient.
            ossClient.shutdown();
        }
    }
}

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region where the bucket is located. For example, for China (Hangzhou), set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# Specify the general-purpose Alibaba Cloud region ID.
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# If the image is in the root directory of the bucket, specify the image name. If the image is not in the root directory, specify the full path, for example, exampledir/example.jpg.
key = 'example.jpg'

# Construct the processing instruction for image label detection.
process = 'image/labels'

try:
    # Use the get_object method and pass the processing instruction through the process parameter.
    result = bucket.get_object(key, process=process)

    # Read and print the information.
    image_labels = result.read().decode('utf-8')
    print("Image Labels:")
    print(image_labels)
except oss2.exceptions.OssError as e:
    print("Error:", e)

package main

import (
	"fmt"
	"io"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain temporary access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, for China (Hangzhou), set it to https://oss-cn-hangzhou.aliyuncs.com. For other regions, specify the actual endpoint.
	// Set yourRegion to the general-purpose Alibaba Cloud region ID, for example, cn-hangzhou.
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"

	bucket, err := client.Bucket(bucketName)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// If the image is in the root directory of the bucket, specify the image name. If the image is not in the root directory, specify the full path, for example, exampledir/example.jpg.
	// Use the oss.Process method to construct the processing instruction for image label detection.
	body, err := bucket.GetObject("example.jpg", oss.Process("image/labels"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	defer body.Close()

	data, err := io.ReadAll(body)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Println("data:", string(data))
}

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

try {
    // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
    $provider = new EnvironmentVariableCredentialsProvider(); 
    // Specify the endpoint of the region where the bucket is located. For example, for China (Hangzhou), set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
    $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
    // Specify the bucket name, for example, examplebucket.
    $bucket = 'examplebucket';
    // If the image is in the root directory of the bucket, specify the image name. If the image is not in the root directory, specify the full path, for example, exampledir/example.jpg.
    $key = 'example.jpg'; 

    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // Specify the general-purpose Alibaba Cloud region ID.
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
  // Construct the processing instruction for image label detection.
  $options[$ossClient::OSS_PROCESS] = "image/labels";
  $result = $ossClient->getObject($bucket,$key,$options);
  var_dump($result);
} catch (OssException $e) {
  printf($e->getMessage() . "\n");
  return;

Parameters

Action: image/labels

Request parameters

Response parameters

Related API operations

If your application requires a high degree of customization, you can make REST API requests directly. This requires you to write code to calculate the signature. For more information about how to calculate the `Authorization` request header, see Signature Version 4 (recommended).

You can process images by adding the `x-oss-process` parameter to the GetObject operation. For more information, see GetObject.

GET /example.jpg?x-oss-process=image/labels HTTP/1.1
Host: image-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 21 Jul 2023 08:30:25 GMT
Authorization: SignatureValue

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 21 Jul 2023 08:30:26 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
x-oss-request-id: 64BA42225DFDD13437ECD00E
Last-Modified: Mon, 10 Jul 2023 13:07:30 GMT
x-oss-object-type: Normal
x-oss-hash-crc64ecma: 13420962247653419692
x-oss-storage-class: Standard
x-oss-ec: 0048-00000104
Content-Disposition: attachment
x-oss-force-download: true
x-oss-server-time: 489
Content-Encoding: gzip

{
    "Labels":[
        {
            "CentricScore": 0.823,
            "LabelConfidence": 1.0,
            "LabelLevel": 2,
            "LabelName": "Outerwear",
            "Language": "zh-Hans",
            "ParentLabelName": "Clothing"
        },
        { 
            "CentricScore": 0.721,
            "LabelConfidence": 0.735,
            "LabelLevel": 2,
            "LabelName": "Apparel",
            "Language": "zh-Hans",
            "ParentLabelName": "Clothing"
        },
    		......,
    ],
    "RequestId": "0EC0B6EC-EB16-5EF4-812B-EF3A60C7D20D"
}
    

GET /example.jpg?x-oss-process=image/labels,thr_0.85 HTTP/1.1
Host: image-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 21 Jul 2023 08:44:58 GMT
Authorization: SignatureValue

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 21 Jul 2023 08:45:00 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
x-oss-request-id: 64BA458C7FFDC2383651DF09
Last-Modified: Mon, 10 Jul 2023 13:07:30 GMT
x-oss-object-type: Normal
x-oss-hash-crc64ecma: 13420962247653419692
x-oss-storage-class: Standard
x-oss-ec: 0048-00000104
Content-Disposition: attachment
x-oss-force-download: true
x-oss-server-time: 421
Content-Encoding: gzip

{
  "RequestId": "B7BDAFD5-C0AF-5042-A749-88BF6E4F2712", 
  "Labels": [
     {
      	"CentricScore": 0.797,
      	"Language": "zh-Hans",
      	"LabelConfidence": 0.927,
      	"LabelName": "Apparel",
      	"LabelLevel": 2,
      	"ParentLabelName": "Clothing"
      },
        ......,
   ]
}

Billing

Image label detection calls the IMM service. This call generates billable items for both OSS and IMM.

• OSS: For more information about pricing, see OSS Pricing

  API	Billable item	Description
  GetObject	GET requests	Billed based on the number of successful requests.
  	Outbound traffic over the internet	If you call the GetObject operation using a public endpoint (for example, oss-cn-hangzhou.aliyuncs.com) or an acceleration endpoint (for example, oss-accelerate.aliyuncs.com), you are charged for outbound traffic over the internet. The fee is based on the data volume.
  	Volume of retrieved Infrequent Access (IA) data	If the retrieved data is stored in the Infrequent Access (IA) storage class, you are charged for data retrieval. The fee is based on the volume of retrieved data.
  	Volume of retrieved data using real-time access of Archive objects	If you read an Archive object from a bucket for which real-time access of Archive objects is enabled, you are charged for data retrieval. The fee is based on the volume of retrieved data.
  	Transfer acceleration	If you enable transfer acceleration and use an acceleration endpoint to access your bucket, you are charged for transfer acceleration. The fee is based on the data volume.
  HeadObject	GET requests	Billed based on the number of successful requests.

• IMM: For more information about pricing, see IMM billable items

  Important

  Starting from 11:00 on July 28, 2025 (UTC+8), the price for the IMM image label detection service will remain unchanged, but the name of the billable item will be changed from ImageClassification to ImageLabel. For more information, see Announcement on IMM Billing Adjustments.

  API	Billable item	Description
  DetectImageLabels	ImageLabel	Billed based on the number of successful requests.