Todos os produtos
Search
Central de documentação

Object Storage Service:Detecção de rótulos de imagem

Última atualização: Jul 03, 2026

Marque automaticamente as imagens armazenadas no OSS ao detectar cenas, objetos e eventos presentes nelas. A detecção de rótulos de imagem abrange milhares de rótulos em mais de 30 categorias, permitindo criar pipelines de classificação de imagens e recomendação de conteúdo sem anotação manual.

Casos de uso

  • Identificação de conteúdo: reconheça itens e cenas em fotos enviadas por usuários para aplicativos de reconhecimento de objetos ou plataformas de conhecimento.

  • Álbuns inteligentes: agrupe imagens automaticamente por conteúdo para organizar álbuns de fotos de forma inteligente e em escala.

  • Análise de cena: aplique rótulos específicos de cena às imagens para reduzir custos com anotação manual e acelerar a categorização de conteúdo.

  • Operações de conteúdo: extraia dados de rótulos para impulsionar recomendações de conteúdo em redes sociais, portais de notícias e plataformas de e-commerce.

Como funciona

A detecção de rótulos de imagem utiliza o parâmetro x-oss-process com a ação image/labels. O OSS encaminha a solicitação ao Intelligent Media Management (IMM), que analisa a imagem e retorna um array JSON com os rótulos detectados, incluindo pontuações de confiança e hierarquia de categorias.

O sistema processa todas as solicitações de forma síncrona. Apenas o acesso autenticado tem suporte.

Pré-requisitos

Antes de começar, certifique-se de ter:

Detectar rótulos de imagem

Os exemplos a seguir mostram como detectar rótulos usando SDKs comuns. Adapte o código desses exemplos para outros SDKs.

Python

Use o Python SDK 2.18.4 ou posterior.

# -*- 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 o Java SDK 3.17.4 ou posterior.

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 o Go SDK 3.0.2 ou posterior.

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 o PHP SDK 2.7.0 ou posterior.

<?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;
}

Referência da API

Ação: image/labels

Parâmetros da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Exemplo

thr

float

Não

Limiar de pontuação de confiança. Rótulos com pontuação abaixo deste valor são excluídos da resposta. Intervalo válido: [0, 1]. Padrão: 0.7.

0.5

Para usar o parâmetro com a API REST, adicione-o à string de ação: image/labels,thr_0.85.

Campos da resposta

Cada item no array Labels contém:

Campo

Descrição

Exemplo

LabelName

Nome do rótulo detectado — um objeto (por exemplo, Outerwear), cena, ação ou conceito.

"Outerwear"

ParentLabelName

Categoria pai. Os rótulos seguem uma hierarquia de dois níveis: um rótulo pai (nível 1) contém um ou mais rótulos filhos (nível 2).

"Clothing"

LabelLevel

Nível na hierarquia. 1 = rótulo pai; 2 = rótulo filho.

2

LabelConfidence

Pontuação de confiança para este rótulo, variando de 0 a 1. Valores mais altos indicam maior confiança.

0.927

CentricScore

Pontuação que indica quão central ou proeminente é o assunto detectado na imagem.

0.797

Language

Idioma do nome do rótulo.

"zh-Hans"

Para obter a lista completa de parâmetros de resposta, consulte DetectImageLabels.

Exemplos

Obter rótulos sem limiar

Solicitação:

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

Resposta:

{
    "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"
}

Obter rótulos com limiar

Defina thr como 0.85 para retornar apenas rótulos com pontuação de confiança igual ou superior a 0,85.

Solicitação:

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

Resposta:

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

Para acesso direto via API REST, calcule o cabeçalho Authorization usando a Assinatura Versão 4. Passe a instrução de processamento pelo parâmetro x-oss-process em uma solicitação GetObject.

Limitações

Limite

Valor

Formatos suportados

JPG, PNG, JPEG

Tamanho máximo da imagem

20 MB

Dimensões máximas da imagem

30.000 px em qualquer lado

Total máximo de pixels

250 milhões

Modo de processamento

Apenas síncrono (via x-oss-process)

Controle de acesso

Acesso anônimo negado

Faturamento

A detecção de rótulos de imagem chama o serviço IMM e gera itens faturáveis tanto para o OSS quanto para o IMM.

Cobranças do OSS — consulte Preços do OSS para detalhes.

API

Item faturável

Descrição

GetObject

Solicitações GET

Faturado por solicitação bem-sucedida.

GetObject

Tráfego de saída pela internet

Aplicável quando acessado via endpoint público (por exemplo, oss-cn-hangzhou.aliyuncs.com) ou endpoint de aceleração (por exemplo, oss-accelerate.aliyuncs.com). Faturado por volume de dados.

GetObject

Volume de dados recuperados de Acesso Infrequente (IA)

Aplicável quando a imagem está armazenada na classe de armazenamento IA. Faturado por volume de dados.

GetObject

Volume de dados recuperados com acesso em tempo real de objetos Archive

Aplicável ao ler um objeto Archive de um bucket com acesso em tempo real ativado. Faturado por volume de dados.

GetObject

Aceleração de transferência

Aplicável quando a aceleração de transferência está ativada e um endpoint de aceleração é utilizado. Faturado por volume de dados.

HeadObject

Solicitações GET

Faturado por solicitação bem-sucedida.

Cobranças do IMM — consulte Itens faturáveis do IMM para detalhes.

API

Item faturável

Descrição

DetectImageLabels

ImageLabel

Faturado por solicitação bem-sucedida.

Importante

A partir das 11:00 de 28 de julho de 2025 (UTC+8), o nome do item faturável muda de ImageClassification para ImageLabel. O preço permanece inalterado. Para mais detalhes, consulte Comunicado sobre ajustes de faturamento do IMM.

Recursos relacionados