All Products
Search
Document Center

Intelligent Media Management:Image label detection

Last Updated:Mar 01, 2026

Image label detection identifies scenes, objects, and events in images and returns structured labels. The feature supports thousands of labels across more than 30 categories, organized in a hierarchical taxonomy.

Use cases

ScenarioDescription
Content recognitionDetect items, scenes, and other information in captured or uploaded images for object recognition or educational applications.
Smart albumClassify images automatically based on content to organize photo albums and galleries without manual effort.
Scene analysisDetect objects and scenes in images, then apply content labels to reduce manual annotation costs.
Content operationsRetrieve image labels for content recommendation on social media, news, and e-commerce platforms.

Limits

ConstraintLimit
Supported image formatsPNG, JPG, JPEG
Maximum image file size20 MB
Maximum image height or width30,000 pixels
Maximum total pixels250 million

Prerequisites

Before you begin, make sure that you have:

Note

Create a project programmatically by calling the CreateProject API operation. To view existing projects in a region, call ListProjects.

Detect image labels

Call the DetectImageLabels API operation to detect labels in an image.

Request parameters

ParameterTypeDescription
ProjectNameStringThe name of the IMM project.
SourceURIStringThe OSS URI of the image, in the format oss://bucket-name/object-key.
ThresholdFloatThe minimum confidence score for returned labels. Labels below this threshold are filtered out. Example: 0.7.

Request example

{
    "ProjectName": "test-project",
    "SourceURI": "oss://test-bucket/test-object.jpg",
    "Threshold": 0.7
}

Response fields

Each label in the Labels array contains the following fields:

FieldTypeDescription
LabelNameStringThe name of the detected label, such as Dog, Building, or Camping.
LabelConfidenceFloatThe confidence score of the label, ranging from 0 to 1. Higher values indicate greater certainty.
CentricScoreFloatA score indicating how prominent or central the labeled object is within the image. Higher values mean the object is more visually prominent.
LabelLevelIntegerThe hierarchy depth of the label. 1 = top-level category, 2 = mid-level category, 3 = fine-grained label.
ParentLabelNameStringThe name of the parent label in the taxonomy. Empty for top-level labels.
LanguageStringThe language of the label taxonomy, such as zh-Hans.

The response also includes a RequestId field that uniquely identifies each API call.

Response example

{
  "RequestId": "91C92EBA-5E51-50C8-B51B-8C3BDC66EB86",
  "Labels": [
    {
      "CentricScore": 0.797,
      "Language": "zh-Hans",
      "LabelConfidence": 1,
      "LabelName": "Clothing",
      "LabelLevel": 2,
      "ParentLabelName": "Clothes"
    },
    {
      "CentricScore": 0.695,
      "Language": "zh-Hans",
      "LabelConfidence": 1,
      "LabelName": "Carnivore",
      "LabelLevel": 2,
      "ParentLabelName": "Wild Animal"
    },
    {
      "CentricScore": 0.723,
      "Language": "zh-Hans",
      "LabelConfidence": 0.987,
      "LabelName": "Tent",
      "LabelLevel": 2,
      "ParentLabelName": "Other Scenes"
    },
    {
      "CentricScore": 0.695,
      "Language": "zh-Hans",
      "LabelConfidence": 0.949,
      "LabelName": "Pet",
      "LabelLevel": 1,
      "ParentLabelName": ""
    },
    {
      "CentricScore": 0.695,
      "Language": "zh-Hans",
      "LabelConfidence": 0.939,
      "LabelName": "Dog",
      "LabelLevel": 3,
      "ParentLabelName": "Pet Dog"
    },
    {
      "CentricScore": 0.803,
      "Language": "zh-Hans",
      "LabelConfidence": 0.924,
      "LabelName": "Person",
      "LabelLevel": 2,
      "ParentLabelName": "Face"
    },
    {
      "CentricScore": 0.689,
      "Language": "zh-Hans",
      "LabelConfidence": 0.885,
      "LabelName": "Camping",
      "LabelLevel": 2,
      "ParentLabelName": "Entertainment"
    }
  ]
}
Note

The response above is abbreviated. A typical response contains all labels that meet the specified Threshold. In this example, the image contains labels such as Clothes, Wild Animal, Pet, Face, and Entertainment at the top level, with finer-grained labels like Dog, Tent, Camping, and Person nested within their respective categories.

Sample code (Python)

The following example uses the IMM Python SDK to detect image labels.

# -*- coding: utf-8 -*-
import sys
import os
from typing import List

from alibabacloud_imm20200930.client import Client as imm20200930Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_imm20200930 import models as imm_20200930_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client(
        access_key_id: str,
        access_key_secret: str,
    ) -> imm20200930Client:
        """
        Initialize the client with an AccessKey ID and AccessKey secret.
        @param access_key_id:
        @param access_key_secret:
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config(
            access_key_id=access_key_id,
            access_key_secret=access_key_secret
        )
        # Specify the endpoint of IMM.
        config.endpoint = f'imm.cn-beijing.aliyuncs.com'
        return imm20200930Client(config)

    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        # Obtain credentials from environment variables.
        # Do not hardcode AccessKey credentials in your code.
        imm_access_key_id = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
        imm_access_key_secret = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        # Initialize the client.
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        detect_image_labels_request = imm_20200930_models.DetectImageLabelsRequest(
            project_name='test-project',
            source_uri='oss://test-bucket/test-object.jpg',
            threshold=0.7
        )
        runtime = util_models.RuntimeOptions()
        try:
            # Print the return value of the API operation.
            client.detect_image_labels_with_options(detect_image_labels_request, runtime)
        except Exception as error:
            # Print the error message if the request fails.
            UtilClient.assert_as_string(error.message)

    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        # Obtain credentials from environment variables.
        # Do not hardcode AccessKey credentials in your code.
        imm_access_key_id = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
        imm_access_key_secret = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        # Initialize the client.
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        detect_image_labels_request = imm_20200930_models.DetectImageLabelsRequest(
            project_name='test-project',
            source_uri='oss://test-bucket/test-object.jpg',
            threshold=0.7
        )
        runtime = util_models.RuntimeOptions()
        try:
            # Print the return value of the API operation.
            await client.detect_image_labels_with_options_async(detect_image_labels_request, runtime)
        except Exception as error:
            # Print the error message if the request fails.
            UtilClient.assert_as_string(error.message)


if __name__ == '__main__':
    Sample.main(sys.argv[1:])
Important

Use a RAM user instead of your Alibaba Cloud account to call API operations. Store AccessKey credentials in environment variables (ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET) rather than hardcoding them in your source code.

Billing

Image label detection incurs charges for both Object Storage Service (OSS) and IMM.

OSS billing

APIBillable itemDescription
GetObjectGET requestsBilled based on the number of successful requests.
GetObjectInfrequent Access (IA) data retrievalIf retrieving IA data, charged based on the volume of retrieved data.
GetObjectArchive real-time access data retrievalIf reading an Archive object from a bucket with real-time access enabled, charged based on the size of retrieved data.
GetObjectTransfer accelerationIf transfer acceleration is enabled and an acceleration endpoint is used, charged based on the data size.
HeadObjectGET requestsBilled based on the number of successful requests.

For full pricing details, see OSS Pricing.

IMM billing

APIBillable itemDescription
DetectImageLabelsImageLabelBilled based on the number of successful requests.
Important

Starting at 11:00 on July 28, 2025 (UTC+8), the billable item for IMM image label detection changed from ImageClassification to ImageLabel. For details, see Notice on IMM billing adjustment.

For full pricing details, see IMM billable items.

FAQ

Does image label detection support extracting text, dates, or locations from images as labels?

No. Image label detection identifies visual content such as objects, scenes, and events. It does not perform optical character recognition (OCR) or extract metadata.

To extract text from images, use image semantic search. After extracting text, parse it for dates or organization names. To retrieve the location where a photo was taken, read the GPS data from the image's Exchangeable Image File Format (EXIF) metadata through an image information API operation.

Note

For images containing violent, pornographic, or other sensitive content, automatic detection may not be sufficiently sensitive or accurate. Manual review may be required in some cases.