All Products
Search

This Product

    Object Storage Service:Image label detection

    Document Center

    Object Storage Service:Image label detection

    Last Updated:Feb 05, 2025

    You can use image label detection to detect image content, such as scenes, objects, and events, and automatically label images. This topic describes the parameters that you can specify to use image label detection and provides examples on how to use image label detection.

    Overview

    Image label detection recognizes image content such as scenes, objects, and events and automatically labels images. IMM provides thousands of image labels that fall into more than 30 categories. The following table lists label categories.

    图片标签检测..jpeg

    Scenarios

    Scenario

    Description

    Content recognition

    You can use image label detection to build image content recognition applications that involve object identification and science popularization. These applications can recognize information, such as objects and scenes in images.

    Photo and album management

    Photos in a photo album are automatically classified based on the image content. This enables efficient and automated photo management.

    Scene analysis

    Image content is automatically analyzed and labeled, which improves analysis efficiency and reduces manual labeling costs.

    Content marketing

    You can use image label detection to improve content marketing on platforms, such as social networking, news, and e-commerce platforms.

    Prerequisites

    • Intelligent Media Management (IMM) is activated. For information, see Activate IMM.

    • An Intelligent Media Management (IMM) project is bound to a bucket. For more information about how to bind an IMM project to a bucket in the OSS console, see Get started. For more information about how to bind an IMM project to a bucket by calling an API operation, see AttachOSSBucket.

    Usage notes

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

    • Anonymous access will be denied.

    • You must have the required permissions to use the feature. For more information, see permissions.

    • Only JPG, PNG, and JPEG are supported.

    • The following image size limits apply:

      • The image to detect cannot exceed 20 MB in size.

      • The height or width of the image to detect cannot exceed 30,000 pixels.

      • The number of total pixels of the image cannot exceed 250,000,000.

    Parameter description

    Action: image/labels

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    thr

    int

    No

    Specifies that labels whose confidence is lower than the specified threshold are not displayed. Valid values: 0 to 100. Default value: 70.

    50

    Response parameters

    Note

    For more information about the response parameters, see DetectImageLabels.

    Examples

    Use OSS SDKs

    The following sample code provides examples on how to detect labels in an image by using OSS SDKs for common programming languages. If you want to detect labels in an image by using other programming languages, modify the parameters based on the following sample code.

    Java

    OSS SDK for Java 3.17.4 or later is required. 

    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 {
        // Specify the endpoint of the region in which the bucket is located. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou. 
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. 
        String bucketName = "examplebucket";
        // If the image is stored in the root directory of the bucket, enter the image name. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: exampledir/example.jpg. 
        String key = "example.jpg";

        // Create an OSSClient instance. 
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Create a processing instruction to detect labels in the image. 
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
            getObjectRequest.setProcess("image/labels");

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

            // Read and display the labels. 
            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 instance. 
            ossClient.shutdown();
        }
    }
}

    Python

    OSS SDK for Python 2.18.4 or later is required. 

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

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

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

# If the image is stored in the root directory of the bucket, enter the image name. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: exampledir/example.jpg. 
key = 'example.jpg'

# Create a processing instruction to detect labels in the image. 
process = 'image/labels'

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

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

    Go

    OSS SDK for Go 3.0.2 or later is required. 

    package main

import (
	"fmt"
	"io"
	"os"

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

func main() {
	// Obtain the temporary access credentials from the environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Create an OSSClient instance. 
	// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint. 
	// Specify the ID of the Alibaba Cloud region in which the bucket is located. 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 name of the bucket. Example: examplebucket. 
	bucketName := "examplebucket"

	bucket, err := client.Bucket(bucketName)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// If the image is stored in the root directory of the bucket, enter the image name. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: exampledir/example.jpg. 
	// Use the oss.Process method to create a processing instruction to detect labels in the image. 
	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

    OSS SDK for PHP 2.7.0 or later is required. 

    <?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 you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
    $provider = new EnvironmentVariableCredentialsProvider(); 
    // Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket = 'examplebucket';
    // If the image is stored in the root directory of the bucket, enter the image name. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: exampledir/example.jpg. 
    $key = 'example.jpg'; 

    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. 
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
  // Create a processing instruction to detect labels in the image. 
  $options[$ossClient::OSS_PROCESS] = "image/labels";
  $result = $ossClient->getObject($bucket,$key,$options);
  var_dump($result);
} catch (OssException $e) {
  printf($e->getMessage() . "\n");
  return;
}

    Use RESTful APIs

    If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information about how to calculate the Authorization header, see (Recommended) Include a V4 signature in the Authorization header.

    You can process images by specifying the x-oss-process parameter in the GetObject request. For more information, see GetObject.

    Obtain the labels of an image without specifying the thr parameter

    The thr parameter

    Leave the thr parameter empty.

    Sample request

    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

    Sample success response

    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": "Coat",
            "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"
}

    Obtain the labels of an image by specifying the thr parameter

    The thr parameter

    • thr: 85

    Sample request

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

    Sample success response

    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"
      },
        ......,
   ]
}