Image label detection function usage and billing - Object Storage Service

Automatically tag images stored in OSS by detecting the scenes, objects, and events they contain. Image label detection covers thousands of labels across more than 30 categories—letting you build image classification and content recommendation pipelines without manual annotation.

Use cases

Content identification: Recognize items and scenes in user-uploaded photos for object recognition apps or knowledge platforms.
Smart albums: Automatically group images by content, enabling intelligent photo album organization at scale.
Scene analysis: Tag images with scene-specific labels to reduce manual annotation costs and speed up content categorization.
Content operations: Extract label data to power content recommendations on social media, news, and e-commerce platforms.

How it works

Image label detection uses the x-oss-process parameter with the image/labels action. OSS forwards the request to Intelligent Media Management (IMM), which analyzes the image and returns a JSON array of detected labels with confidence scores and category hierarchy.

All requests are processed synchronously. Only authenticated access is supported.

Prerequisites

Before you begin, make sure you have:

Activated Intelligent Media Management (IMM)
Created a bucket and uploaded the images to process
Created and attached an IMM project to the bucket—via the OSS console or via API. The IMM project must be in the same region as the bucket.
Granted the required permissions

Detect image labels

The following examples show how to detect labels using common SDKs. Adapt the code from these examples for other SDKs.

Python

Use Python SDK 2.18.4 or later.

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

# Obtain access credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set the endpoint for the region where the bucket is located.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# Specify the object key. Include the full path if the image is not in the root directory,
# for example, exampledir/example.jpg.
key = 'example.jpg'

process = 'image/labels'

try:
    result = bucket.get_object(key, process=process)
    image_labels = result.read().decode('utf-8')
    print("Image labels:")
    print(image_labels)
except oss2.exceptions.OssError as e:
    print("Error:", e)

Java

Use Java SDK 3.17.4 or later.

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 the endpoint for the region where the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables.
        // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        String bucketName = "examplebucket";
        // Specify the object key. Include the full path if the image is not in the root directory,
        // for example, exampledir/example.jpg.
        String key = "example.jpg";

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

        try {
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
            getObjectRequest.setProcess("image/labels");

            OSSObject ossObject = ossClient.getObject(getObjectRequest);

            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 {
            ossClient.shutdown();
        }
    }
}

Go

Use Go SDK 3.0.2 or later.

package main

import (
	"fmt"
	"io"
	"os"

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

func main() {
	// Obtain access credentials from environment variables.
	// Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Set the endpoint for the region where the bucket is located.
	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)
	}

	bucket, err := client.Bucket("examplebucket")
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Specify the object key. Include the full path if the image is not in the root directory,
	// for example, exampledir/example.jpg.
	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("Image labels:", string(data))
}

PHP

Use PHP SDK 2.7.0 or later.

<?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.
    // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
    $provider = new EnvironmentVariableCredentialsProvider();
    // Set the endpoint for the region where the bucket is located.
    $endpoint = 'https://oss-cn-hangzhou.aliyuncs.com';
    $bucket = 'examplebucket';
    // Specify the object key. Include the full path if the image is not in the root directory,
    // for example, exampledir/example.jpg.
    $key = 'example.jpg';

    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    $options[$ossClient::OSS_PROCESS] = "image/labels";
    $result = $ossClient->getObject($bucket, $key, $options);
    var_dump($result);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

API reference

Action: image/labels

Request parameters

Parameter	Type	Required	Description	Example
`thr`	float	No	Confidence score threshold. Labels with a score below this value are excluded from the response. Valid range: [0, 1]. Default: `0.7`.	`0.5`

To use the parameter with the REST API, append it to the action string: image/labels,thr_0.85.

Response fields

Each item in the Labels array contains:

Field	Description	Example
`LabelName`	The detected label name—an object (for example, Outerwear), scene, action, or concept.	`"Outerwear"`
`ParentLabelName`	The parent category. Labels are organized in a two-level hierarchy: a parent label (level 1) contains one or more child labels (level 2).	`"Clothing"`
`LabelLevel`	The level in the hierarchy. `1` = parent label; `2` = child label.	`2`
`LabelConfidence`	The confidence score for this label, from 0 to 1. Higher values indicate greater confidence.	`0.927`
`CentricScore`	A score indicating how central or prominent the detected subject is in the image.	`0.797`
`Language`	The language of the label name.	`"zh-Hans"`

For the full list of response parameters, see DetectImageLabels.

Examples

Get labels without a threshold

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

Response:

{
    "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 labels with a threshold

Set thr to 0.85 to return only labels with a confidence score of 0.85 or higher.

Request:

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

Response:

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

For direct REST API access, calculate the Authorization header using Signature Version 4. Pass the processing instruction via the x-oss-process parameter in a GetObject request.

Limitations

Limit	Value
Supported formats	JPG, PNG, JPEG
Maximum image size	20 MB
Maximum image dimensions	30,000 px on either side
Maximum total pixels	250 million
Processing mode	Synchronous only (via `x-oss-process`)
Access control	Anonymous access is denied

Billing

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

OSS charges — see OSS pricing for details.

API	Billable item	Description
GetObject	GET requests	Billed per successful request.
GetObject	Outbound traffic over the internet	Applies when accessed via a public endpoint (for example, `oss-cn-hangzhou.aliyuncs.com`) or an acceleration endpoint (for example, `oss-accelerate.aliyuncs.com`). Billed by data volume.
GetObject	Volume of retrieved Infrequent Access (IA) data	Applies when the image is stored in the IA storage class. Billed by data volume.
GetObject	Volume of retrieved data using real-time access of Archive objects	Applies when reading an Archive object from a bucket with real-time access enabled. Billed by data volume.
GetObject	Transfer acceleration	Applies when transfer acceleration is enabled and an acceleration endpoint is used. Billed by data volume.
HeadObject	GET requests	Billed per successful request.

IMM charges — see IMM billable items for details.

API	Billable item	Description
DetectImageLabels	ImageLabel	Billed per successful request.

Important

Starting from 11:00 on July 28, 2025 (UTC+8), the billable item name changes from ImageClassification to ImageLabel. The price remains unchanged. For details, see Announcement on IMM billing adjustments.

Related resources

DetectImageLabels API reference — full response parameter details and error codes
IMM billable items — pricing details for IMM operations
OSS pricing — pricing details for OSS operations