Tous les produits
Search
Centre de documentation

Object Storage Service:Génération de sprites

Dernière mise à jour :Aug 08, 2026

Un sprite CSS (Cascading Style Sheets) regroupe plusieurs images dans un seul fichier image. Les sprites optimisent principalement les performances des sites web et le développement frontend. Grâce à la propriété background-position du CSS, vous réduisez les requêtes HTTP, ce qui améliore la vitesse de chargement des pages et l'expérience utilisateur. La fonctionnalité de génération de sprites extrait des images vidéo et les assemble en un sprite. Cette rubrique présente les paramètres de génération de sprites à partir d'images instantanées vidéo et propose des exemples.

Remarques

  • La génération de sprites à partir d'images instantanées vidéo prend uniquement en charge le traitement asynchrone (x-oss-async-process).

  • Si l'horodatage ou le flux vidéo est corrompu, la génération du sprite peut échouer ou produire un nombre incorrect d'images.

  • Avant d'utiliser cette fonctionnalité, vous devez associer un projet IMM. Pour savoir comment associer un projet depuis la console ou via une API, consultez les rubriques Démarrage rapide et AttachOSSBucket - Associer un bucket OSS.

Paramètres

Action : video/sprite

Le tableau suivant décrit les paramètres.

Paramètre

Type

Obligatoire

Description

ss

int

Non

Heure de début de la génération du sprite. Unité : milliseconde. Valeurs valides :

  • 0 (par défaut) : depuis le début de la vidéo.

  • Valeur supérieure à 0 : à partir de la milliseconde spécifiée.

f

string

Oui

Format de sortie du sprite. Valeurs valides :

  • jpg

  • png

Remarque

La résolution maximale est de 16 384 px × 16 384 px.

m

string

Non

Mode de capture des images pour les sous-images du sprite. La valeur par défaut est inter. Valeurs valides :

  • inter : mode à intervalle fixe. L'intervalle de capture des images est déterminé par le paramètre inter, et le nombre d'images capturées par le paramètre num.

  • key : mode image clé. Seules les images IDR de la vidéo source sont capturées. Le nombre d'images capturées est déterminé par le paramètre num. Le paramètre inter n'est pas pris en compte dans ce mode.

  • avg : mode à intervalle moyen. Les images sont capturées à intervalles réguliers selon le paramètre num. Le paramètre inter n'est pas pris en compte dans ce mode.

  • dhash : mode dhash. Les images sont capturées à intervalles fixes. Les images les plus significatives, dont le contenu change au-delà d'un seuil, sont sélectionnées. L'intervalle de capture est déterminé par le paramètre inter, le nombre d'images capturées par le paramètre num et le seuil par le paramètre thr.

thr

int

Non

Seuil de capture des images pour les sous-images du sprite en mode dhash. Plus le seuil est élevé, moins il y a d'images capturées. Valeurs valides : [0, 100]. Valeur par défaut : 0.

Remarque

Ce paramètre n'est valide qu'en mode dhash.

Le mode dhash est sensible au seuil. Définissez ce paramètre sur une valeur inférieure ou égale à 25 et ajustez-la si nécessaire.

num

int

Non

Nombre d'images à capturer pour les sous-images du sprite. Valeur par défaut : 0, ce qui signifie qu'il n'y a aucune limite sur le nombre d'images capturées. La valeur par défaut a des significations différentes selon les modes de capture :

  • Mode à intervalle fixe : les images sont capturées jusqu'à la fin de la vidéo.

  • Mode image clé : les images sont capturées jusqu'à la fin de la vidéo.

  • Mode à intervalle moyen : ce paramètre ne peut pas être défini sur 0.

  • Mode dhash : toutes les images dont le changement de contenu dépasse la valeur du paramètre thr sont capturées.

Important

Le nombre réel d'images capturées peut être inférieur à la valeur spécifiée en raison de la durée de la vidéo et des paramètres de capture.

inter

int

Non

Intervalle de capture des images pour les sous-images du sprite. Unité : milliseconde. Valeur par défaut : 0, ce qui signifie que toutes les images vidéo sont capturées.

Remarque

Si la valeur de ce paramètre est inférieure à l'intervalle entre les images (l'inverse de la fréquence d'images) de la vidéo source, les images sont capturées selon l'intervalle de la vidéo source.

sw

int

Non

Largeur d'une sous-image du sprite. Unité : px. Valeurs valides : [32, 4 096]. Par défaut, la largeur de la sous-image correspond à celle de la vidéo source.

sh

int

Non

Hauteur d'une sous-image du sprite. Unité : px. Valeurs valides : [32, 4 096]. Par défaut, la hauteur de la sous-image correspond à celle de la vidéo source.

psw

int

Non

Pourcentage de la largeur de la sous-image du sprite par rapport à la largeur de la vidéo source. Valeurs valides : (0, 200]. Valeur par défaut : 100.

Remarque

Si vous définissez à la fois les paramètres sw et psw, le paramètre psw est ignoré.

psh

int

Non

Pourcentage de la hauteur de la sous-image du sprite par rapport à la hauteur de la vidéo source. Valeurs valides : (0, 200]. Valeur par défaut : 100.

Remarque

Si vous définissez à la fois les paramètres sh et psh, le paramètre psh est ignoré.

scaletype

string

Non

Mode de mise à l'échelle. Valeurs valides :

  • crop : met à l'échelle et recadre l'image.

  • stretch (par défaut) : étire l'image pour remplir l'espace.

  • fill : met à l'échelle l'image et conserve les bandes noires.

  • fit : met à l'échelle l'image proportionnellement sans bandes noires.

tw

int

Non

Nombre de sous-images par ligne du sprite. Valeur par défaut : 6. Valeurs valides : [1, 100].

th

int

Non

Nombre de sous-images par colonne du sprite. Valeur par défaut : 6. Valeurs valides : [1, 100].

pad

int

Non

Marge intérieure entre les sous-images du sprite. Unité : px. Valeur par défaut : 2. Valeurs valides : [0, 100].

margin

int

Non

Marge extérieure autour des bords du sprite. Unité : px. Valeur par défaut : 2. Valeurs valides : [0, 100].

Remarque

Les paramètres sys/saveas et notify sont également utilisés lors de la génération de sprites à partir d'images instantanées vidéo. Pour plus d'informations, consultez les rubriques Enregistrer sous et Notifications.

Utiliser l'API REST

Important

Si vous ne spécifiez pas d'extension de fichier (comme .jpg) dans le chemin de stockage du sprite de sortie, le système ajoute automatiquement un numéro ordinal au nom de fichier, par exemple _0_1.jpg. Si vous spécifiez une extension, seul le dernier sprite est enregistré. Nous vous recommandons donc de ne pas spécifier d'extension de fichier. Pour personnaliser le numéro ordinal, utilisez les variables liées à ApsaraVideo Media Processing.

Générer un sprite pour l'ensemble de la vidéo en capturant une image toutes les 2 secondes

Vous pouvez générer un sprite couvrant toute la vidéo en capturant une image toutes les 2 secondes. Chaque sprite contient une grille de 3 × 3 sous-images, chaque sous-image ayant une résolution de 200 × 150.

Informations sur le sprite

  • Fichier source

    • Nom de la vidéo : example.mkv

  • Notification de message

    • Rubrique MNS pour les notifications : example-mns-topic

  • Configuration de sortie

    • Informations de capture d'images

      • Format du sprite : jpg

      • Intervalle de capture des sous-images : 2 s

      • Disposition de la grille des sous-images : 3 × 3

      • Résolution des sous-images : 200 × 150

      • Mode de mise à l'échelle des sous-images : crop

      • Marge intérieure entre les sous-images : 0

      • Marge extérieure autour des sous-images : 0

    • Chemin de stockage des fichiers

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

Exemple

// 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

Générer un sprite en capturant des images à intervalles réguliers selon un nombre spécifié

Vous pouvez générer un sprite de 10 × 10 où les sous-images couvrent uniformément l'ensemble de la vidéo. Cela simplifie la logique frontend.

Informations sur le sprite

  • Fichier source

    • Nom de la vidéo : example.mkv

  • Notification de message

    • Rubrique MNS pour les notifications : example-mns-topic

  • Configuration de sortie

    • Informations de capture d'images

      • Format du sprite : jpg

      • Mode de capture des sous-images : avg

      • Disposition de la grille des sous-images : 10 × 10

      • Résolution des sous-images : 1/10 de la vidéo source

      • Mode de mise à l'échelle des sous-images : fit

      • Marge intérieure entre les sous-images : 4

      • Marge extérieure autour des sous-images : 5

    • Chemin de stockage des fichiers

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

Exemple

// 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

Utiliser les SDK

La génération asynchrone de sprites à partir d'images instantanées vidéo est prise en charge uniquement par les SDK pour Java, Python et Go. Pour plus d'informations, consultez la rubrique Installer les SDK.

Java

Le SDK OSS pour Java version 3.17.4 ou ultérieure est requis.

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

Le SDK Python version 2.18.4 ou ultérieure est requis.

# -*- 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

Le SDK Go version 3.0.2 ou ultérieure est requis.

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)
}