Todos os produtos
Search
Central de documentação

Object Storage Service:Sprite generation

Última atualização: Jul 03, 2026

Um sprite CSS (Cascading Style Sheets) é um conjunto de imagens combinadas em um único arquivo. Os sprites são usados principalmente para otimizar o desempenho de sites e no desenvolvimento frontend. Ao utilizar a propriedade background-position do CSS, você reduz as requisições HTTP, o que melhora a velocidade de carregamento da página e a experiência do usuário. Com o recurso de geração de sprites, é possível extrair frames de vídeo e combiná-los em um sprite. Este tópico descreve os parâmetros para gerar sprites a partir de snapshots de vídeo e fornece exemplos.

Observações de uso

  • A geração de sprites a partir de snapshots de vídeo suporta apenas processamento assíncrono (x-oss-async-process).

  • A geração de sprites pode falhar ou produzir uma quantidade incorreta de imagens se o carimbo de data/hora ou o stream do vídeo estiver corrompido.

  • Antes de usar este recurso, anexe um projeto IMM. Para obter mais informações sobre como anexar um projeto no console ou usando uma API, consulte Início rápido e AttachOSSBucket - Anexar um bucket OSS.

Parâmetros

Ação: video/sprite

A tabela a seguir descreve os parâmetros.

Parâmetro

Tipo

Obrigatório

Descrição

ss

int

Não

O horário inicial para gerar um sprite. Unidade: milissegundo. Valores válidos:

  • 0 (padrão): desde o início do vídeo.

  • Valor maior que 0: a partir do milissegundo especificado.

f

string

Sim

O formato de saída do sprite. Valores válidos:

  • jpg

  • png

Nota

A resolução máxima é 16384px × 16384px.

m

string

Não

O modo de captura de frames para subimagens do sprite. O valor padrão é inter. Valores válidos:

  • inter: modo de intervalo fixo. O intervalo de captura de frames é determinado pelo parâmetro inter, e a quantidade de frames capturados é definida pelo parâmetro num.

  • key: modo de keyframe. Apenas frames IDR são capturados do vídeo source. A quantidade de frames capturados é determinada pelo parâmetro num. O parâmetro inter não tem efeito neste modo.

  • avg: modo de intervalo médio. Os frames são capturados em intervalos médios com base no parâmetro num. O parâmetro inter não tem efeito neste modo.

  • dhash: modo dhash. Os frames são capturados em intervalos fixos. São selecionados os frames mais significativos cujo conteúdo muda ao longo do tempo além de um limiar. O intervalo de captura é definido pelo parâmetro inter, a quantidade de frames capturados pelo parâmetro num e o limiar pelo parâmetro thr.

thr

int

Não

O limiar de captura de frames para subimagens do sprite no modo dhash. Um limiar maior resulta em menos frames capturados. Valores válidos: [0, 100]. Valor padrão: 0.

Nota

Este parâmetro é válido apenas no modo dhash.

O modo dhash é sensível ao limiar. Defina este parâmetro com um valor não superior a 25 e ajuste-o conforme necessário.

num

int

Não

A quantidade de frames a serem capturados para as subimagens do sprite. Valor padrão: 0, indicando que não há limite para a quantidade de frames capturados. O valor padrão tem significados diferentes nos diversos modos de captura:

  • Modo de intervalo fixo: os frames são capturados até o final do vídeo.

  • Modo de keyframe: os frames são capturados até o final do vídeo.

  • Modo de intervalo médio: este parâmetro não pode ser definido como 0.

  • Modo dhash: todos os frames cuja mudança de conteúdo excede o valor do parâmetro thr são capturados.

Importante

A quantidade real de frames capturados pode ser menor que o valor especificado devido à duração do vídeo e aos parâmetros de captura.

inter

int

Não

O intervalo para capturar frames das subimagens do sprite. Unidade: milissegundo. Valor padrão: 0, indicando que todos os frames do vídeo são capturados.

Nota

Se o valor deste parâmetro for menor que o intervalo de frames (o recíproco da taxa de frames) do vídeo source, a captura seguirá o intervalo de frames do vídeo original.

sw

int

Não

A largura de uma subimagem do sprite. Unidade: px. Valores válidos: [32, 4096]. Por padrão, a largura da subimagem é igual à largura do vídeo source.

sh

int

Não

A altura de uma subimagem do sprite. Unidade: px. Valores válidos: [32, 4096]. Por padrão, a altura da subimagem é igual à altura do vídeo source.

psw

int

Não

A porcentagem da largura da subimagem do sprite em relação à largura do vídeo source. Valores válidos: (0, 200]. Valor padrão: 100.

Nota

Se você definir os parâmetros sw e psw simultaneamente, o parâmetro psw será ignorado.

psh

int

Não

A porcentagem da altura da subimagem do sprite em relação à altura do vídeo source. Valores válidos: (0, 200]. Valor padrão: 100.

Nota

Se você definir os parâmetros sh e psh simultaneamente, o parâmetro psh será ignorado.

scaletype

string

Não

O modo de dimensionamento. Valores válidos:

  • crop: redimensiona e corta a imagem.

  • stretch (padrão): estica a imagem para preencher o espaço.

  • fill: redimensiona a imagem mantendo as barras pretas.

  • fit: redimensiona a imagem proporcionalmente sem barras pretas.

tw

int

Não

A quantidade de subimagens em cada linha do sprite. Valor padrão: 6. Valores válidos: [1, 100].

th

int

Não

A quantidade de subimagens em cada coluna do sprite. Valor padrão: 6. Valores válidos: [1, 100].

pad

int

Não

O preenchimento entre as subimagens no sprite. Unidade: px. Valor padrão: 2. Valores válidos: [0, 100].

margin

int

Não

A margem ao redor das bordas do sprite. Unidade: px. Valor padrão: 2. Valores válidos: [0, 100].

Nota

Os parâmetros sys/saveas e notify também são utilizados na geração de sprites a partir de snapshots de vídeo. Para obter mais informações, consulte Salvar como e Notificações.

Usar a API REST

Importante

Caso você não especifique uma extensão de arquivo, como .jpg, no caminho de armazenamento do sprite de saída, o sistema adicionará automaticamente um número ordinal ao nome do arquivo, como _0_1.jpg. Se uma extensão for especificada, apenas o último sprite será salvo. Portanto, recomenda-se não especificar uma extensão de arquivo. Para personalizar o número ordinal, utilize variáveis relacionadas ao ApsaraVideo Media Processing.

Gerar um sprite para todo o vídeo capturando um frame a cada 2 segundos

Gere um sprite para todo o vídeo capturando um frame a cada 2 segundos. Cada sprite contém uma grade de subimagens de 3 × 3, e cada subimagem tem resolução de 200 × 150.

Informações do sprite

  • Arquivo source

    • Nome do vídeo: example.mkv

  • Notificação de mensagem

    • Tópico MNS para notificações: example-mns-topic

  • Configuração de saída

    • Informações de captura de frames

      • Formato do sprite: jpg

      • Intervalo de captura de frames para subimagens: 2 s

      • Layout da grade de subimagens: 3 × 3

      • Resolução da subimagem: 200 × 150

      • Modo de dimensionamento da subimagem: crop

      • Preenchimento entre subimagens: 0

      • Margem ao redor das subimagens: 0

    • Caminho de armazenamento de arquivos

      • Arquivo JPG: oss://outbucket/outobjprefix-%d.jpg

Exemplo

// Generate a sprite from the example.mkv video file.
POST /exmaple.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
 
x-oss-async-process=video/sprite,f_jpg,sw_200,sh_150,inter_2000,tw_3,th_3,pad_0,margin_0|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

Gerar um sprite capturando frames em intervalos uniformes com base em uma quantidade especificada

Gere um sprite de 10 × 10 onde as subimagens cobrem uniformemente todo o vídeo. Isso simplifica a lógica do frontend.

Informações do sprite

  • Arquivo source

    • Nome do vídeo: example.mkv

  • Notificação de mensagem

    • Tópico MNS para notificações: example-mns-topic

  • Configuração de saída

    • Informações de captura de frames

      • Formato do sprite: jpg

      • Modo de captura de frames para subimagens: avg

      • Layout da grade de subimagens: 10 × 10

      • Resolução da subimagem: 1/10 do vídeo source

      • Modo de dimensionamento da subimagem: fit

      • Preenchimento entre subimagens: 4

      • Margem ao redor das subimagens: 5

    • Caminho de armazenamento de arquivos

      • Arquivo JPG: oss://outbucket/outobjprefix-%d.jpg

Exemplo

// Generate a sprite from the example.mkv video file.
POST /exmaple.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
 
x-oss-async-process=video/sprite,f_jpg,m_avg,psw_10,psh_10,scaletype_fit,tw_10,th_10,pad_4,margin_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

Usar SDKs

A geração assíncrona de sprites a partir de snapshots de vídeo é suportada apenas pelos SDKs para Java, Python e Go. Para obter mais informações, consulte Instalar SDKs.

Java

É necessário o OSS SDK for Java 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.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;

import java.util.Base64;

public class Demo {
    public static void main(String[] args) throws ClientException {
        // Specify the endpoint of the region where the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region ID that corresponds to the endpoint. Example: cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before you run this 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 bucket name.
        String bucketName = "examplebucket";
        // Specify the filename of the sprite.
        String targetKey = "example.jpg";
        // Specify the name of the source video file.
        String sourceKey = "src.mp4";

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

        try {
            // Configure the parameters for generating a sprite from a video.
            String style = String.format("video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0");
            // Create an asynchronous processing instruction.
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
            String process = String.format("%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0", style, bucketEncoded, targetEncoded);
            // Create an AsyncProcessObjectRequest object.
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            // Execute the asynchronous processing task.
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());

        } finally {
            // Shut down the OSSClient.
            ossClient.shutdown();
        }
    }
}

Python

É necessário o Python SDK 2.18.4 ou posterior.

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

def main():
    # Obtain temporary access credentials from environment variables. Before you run this 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 where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    # Specify the region ID that corresponds to the endpoint. Example: cn-hangzhou.
    region = 'cn-hangzhou'

    # Specify the bucket name.
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    # Specify the name of the source video file.
    source_key = 'src.mp4'

    # Specify the filename of the sprite.
    target_key = 'example.jpg'

    # Configure the parameters for generating a sprite from a video.
    animation_style = 'video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0'

    # Create a processing instruction that includes the storage path and the Base64-encoded bucket name and object name.
    bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
    process = f"{animation_style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}/notify,topic_QXVkaW9Db252ZXJ0"

    try:
        # Execute the asynchronous processing task.
        result = bucket.async_process_object(source_key, process)
        print(f"EventId: {result.event_id}")
        print(f"RequestId: {result.request_id}")
        print(f"TaskId: {result.task_id}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Go

É necessário o Go SDK 3.0.2 ou posterior.

package main

import (
    "encoding/base64"
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "log"
)

func main() {
    // Obtain temporary access credentials from environment variables. Before you run this 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.
    // Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify the endpoint based on your actual region.
    // Set yourRegion to the Alibaba Cloud region ID. 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. Example: examplebucket.
    bucketName := "examplebucket"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }

    // Specify the name of the source video file.
    sourceKey := "src.mp4"
    // Specify the name of the output sprite file.
    targetKey := "example.jpg"

    // Configure the parameters for generating a sprite from a video.
    animationStyle := "video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0"

    // Create a processing instruction that includes the storage path and the Base64-encoded bucket name and object name.
    bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
    targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
    process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v/notify,topic_QXVkaW9Db252ZXJ0", animationStyle, bucketNameEncoded, targetKeyEncoded)

    // Execute the asynchronous processing task.
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
    log.Fatalf("Failed to async process object: %s", err)
    }

    fmt.Printf("EventId: %s\n", result.EventId)
    fmt.Printf("RequestId: %s\n", result.RequestId)
    fmt.Printf("TaskId: %s\n", result.TaskId)
}