Object Storage Service:Add watermarks

Escenarios

• Protección de derechos de autor: Una marca de agua en sus imágenes indica la titularidad de los derechos de autor y evita el uso no autorizado.

• Promoción de marca: Una marca de agua que contiene el logotipo o nombre de su marca en imágenes, videos o documentos aumenta el reconocimiento de la marca.

• Prevención de alteraciones: Una marca de agua en documentos oficiales, certificados o informes desalienta la manipulación y reduce el riesgo de falsificación.

• Prevención del robo de imágenes: Agregar una marca de agua desalienta el robo de imágenes, ya que las imágenes en línea se copian y republican fácilmente.

• Cumplimiento legal: Algunas leyes o contratos requieren que agregue una marca de agua a contenido específico antes de su publicación.

Límites

• Puede usar URL de objetos, SDK de OSS u operaciones de API para configurar parámetros IMG que se utilizan para procesar imágenes. En este ejemplo, se utilizan URL de objetos. Puede usar URL de objetos para configurar parámetros IMG solo en imágenes de lectura pública. Si desea configurar parámetros IMG para imágenes privadas, utilice SDK de OSS u operaciones de API. Para obtener más información, consulte Image processing methods.

• Las imágenes de marca de agua deben almacenarse en el mismo bucket. Cargue primero las imágenes locales o en línea en el bucket.

• Formatos de marca de agua de imagen compatibles: JPG, PNG, BMP, WebP y TIFF.

• Hasta tres marcas de agua de imagen por imagen. Las marcas de agua no pueden superponerse por completo.

• Las marcas de agua de texto no admiten caracteres chinos tradicionales.

Parámetros

acción: watermark

Los parámetros se agrupan por tipo en las siguientes tablas.

• Parámetros básicos

  Parámetro	Obligatorio	Descripción	Valor
  t	No	Opacidad de la marca de agua.	[0, 100] Predeterminado: 100 (totalmente opaca).
  g	No	Posición de la marca de agua en la imagen.	nw: superior izquierda north: superior centro ne: superior derecha west: medio izquierda center: centro east: medio derecha sw: inferior izquierda south: inferior centro se (predeterminado): inferior derecha Las posiciones se ilustran en el siguiente diagrama.
  x	No	Desplazamiento horizontal desde el borde de la imagen. Se aplica solo cuando g se establece en nw, west, sw, ne, east o se.	[0, 4096] Predeterminado: 10 Unidad: píxeles (px)
  y	No	Desplazamiento vertical desde el borde de la imagen. Se aplica solo cuando g se establece en nw, north, ne, sw, south o se.	[0, 4096] Predeterminado: 10 Unidad: píxeles (px)
  voffset	No	Desplazamiento vertical cuando g se establece en west, center o east.	[-1000, 1000] Predeterminado: 0 Unidad: píxeles (px)
  fill	No	Indica si se debe aplicar mosaico de la marca de agua sobre la imagen de origen. Nota Para utilizar la función de marca de agua en mosaico para marcas de agua de imagen, envíe una solicitud en Quota Center.	1: Aplica mosaico de la marca de agua de imagen o texto sobre la imagen de origen. 0 (predeterminado): No aplica mosaico de la marca de agua sobre la imagen de origen.
  padx	No	Espaciado horizontal entre marcas de agua en mosaico. Se aplica solo cuando fill se establece en 1.	[0, 4096] Predeterminado: 0 Unidad: píxeles (px)
  pady	No	Espaciado vertical entre marcas de agua en mosaico. Se aplica solo cuando fill se establece en 1.	[0, 4096] Predeterminado: 0 Unidad: píxeles (px)

  Estos desplazamientos controlan tanto la posición de una sola marca de agua como el diseño de la marca de agua en mosaico.

  El siguiente diagrama muestra las posiciones de referencia y sus valores correspondientes.

• Parámetros de marca de agua de imagen

  Parámetro	Obligatorio	Descripción	Valor
  image	Sí	Ruta completa del objeto de imagen de marca de agua, codificada en Base64 segura para URL (URL-safe Base64 encoding). Por ejemplo, codifique la ruta image/panda.png para obtener aW1hZ2UvcGFuZGEucG5n. Nota Las imágenes de marca de agua deben ser objetos almacenados en el mismo bucket.	Una cadena codificada en Base64 segura para URL.

• Parámetros de preprocesamiento de imagen de marca de agua

  Puede usar todos los parámetros de las acciones resize, custom crop, indexed slice, rounded corners y rotate para preprocesar la imagen de marca de agua. Además, el preprocesamiento de la imagen de marca de agua admite el parámetro de escalado P:

  Parámetro	Descripción	Valor
  P	Escala la imagen de marca de agua como un porcentaje de las dimensiones de la imagen de origen. Por ejemplo, establecer esto en 10 en una imagen de origen de 100 × 100 px escala la marca de agua a 10 × 10 px. Si la imagen de origen cambia a 200 × 200 px, la marca de agua se escala a 20 × 20 px.	[1, 100]

• Parámetros de marca de agua de texto

  Parámetro	Obligatorio	Descripción	Valor
  text	Sí	Contenido de texto de la marca de agua, codificado en Base64 seguro para URL (URL-safe Base64 encoding).	La cadena de texto no debe exceder los 64 bytes antes de la codificación Base64.
  type	No	Fuente de la marca de agua de texto. El nombre de la fuente debe estar codificado en Base64 seguro para URL.	Para ver las fuentes compatibles y sus valores codificados, consulte font type and encoding table. Predeterminado: wqy-zenhei (codificado como d3F5LXplbmhlaQ)
  color	No	Color de la marca de agua de texto.	Un valor de color hexadecimal RGB. Por ejemplo, 000000 para negro y FFFFFF para blanco. Predeterminado: 000000 (negro)
  size	No	Tamaño de fuente de la marca de agua de texto.	(0, 1000] Predeterminado: 40 Unidad: píxeles (px)
  shadow	No	Opacidad de la sombra de la marca de agua de texto.	[0, 100] Predeterminado: 0 (sin sombra).
  rotate	No	Ángulo de rotación en sentido horario del texto.	[0, 360] Predeterminado: 0 (sin rotación).

  La siguiente tabla enumera las fuentes disponibles y sus valores codificados para el parámetro type.

  Valor del parámetro	Descripción	Valor codificado
  wqy-zenhei	WenQuanYi Zen Hei	d3F5LXplbmhlaQ
  wqy-microhei	WenQuanYi Micro Hei	d3F5LW1pY3JvaGVp
  fangzhengshusong	Fangzheng Shusong	ZmFuZ3poZW5nc2h1c29uZw
  fangzhengkaiti	Fangzheng Kaiti	ZmFuZ3poZW5na2FpdGk
  fangzhengheiti	Fangzheng Heiti	ZmFuZ3poZW5naGVpdGk
  fangzhengfangsong	Fangzheng Fangsong	ZmFuZ3poZW5nZmFuZ3Nvbmc
  droidsansfallback	DroidSansFallback	ZHJvaWRzYW5zZmFsbGJhY2s

• Parámetros de marca de agua de texto e imagen

  Parámetro	Obligatorio	Descripción	Valor
  order	No	Orden de visualización de las marcas de agua de texto e imagen.	0 o 1 0 (predeterminado): La marca de agua de imagen está al frente. 1: La marca de agua de texto está al frente.
  align	No	Alineación de las marcas de agua de texto e imagen.	0, 1 o 2 0: Las marcas de agua están alineadas en la parte superior. 1: Las marcas de agua están alineadas al centro. 2 (predeterminado): Las marcas de agua están alineadas en la parte inferior.
  interval	No	Espaciado entre las marcas de agua de texto e imagen.	[0, 1000] Predeterminado: 0 Unidad: píxeles (px)

Codificación de marca de agua

Parámetros como el contenido de texto, la fuente y el nombre de la imagen deben codificarse en Base64 seguro para URL:

1. Codifique el contenido en Base64.

2. Reemplace los siguientes caracteres en la cadena resultante:

   • Reemplace cada signo más (+) con un guion (-).

   • Reemplace cada barra diagonal (/) con un guion bajo (_).

   • Elimine todos los signos igual (=) finales.

Utilice un codificador base64url para codificar parámetros como contenido de texto, color de texto, fuente y nombre de imagen de marca de agua.

Métodos

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // Specify the endpoint. In this example, the endpoint for the China (Hangzhou) region is used. Specify your actual endpoint.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region where your bucket is located, for example, cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before you run the 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. Example: examplebucket.
        String bucketName = "examplebucket";
        // Specify the full path of the object. The full path cannot contain the bucket name.
        String objectName = "src.jpg";
        // Specify the destination path for the local file, such as D:\\localpath\\example-new.jpg. The file is created or overwritten.
        String pathName = "D:\\dest.jpg";

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

        try {
            // Add a "Hello World" text watermark to the image.
            String image = "image/watermark,text_SGVsbG8gV29ybGQ";
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            request.setProcess(image);
            // Save the processed image to your local machine as example-new.jpg.
            // If you specify only the filename (for example, example-new.jpg) without a full path, the file is saved to the local directory of the project.
            ossClient.getObject(request, new File("D:\\dest.jpg"));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

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

// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
$provider = new 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 bucket name. Example: examplebucket.
$bucket= "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.jpg. The full path cannot contain the bucket name.
$object = "src.jpg";
// Specify the destination path for the local file, such as D:\\localpath\\example-new.jpg. The file is created or overwritten.
// If you specify only the filename (for example, example-new.jpg) without a full path, the file is saved to the local directory of the project.
$download_file = "D:\\dest.jpg";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // Specify the general-purpose region ID.
        "region" => "cn-hangzhou"
    );
$ossClient = new OssClient($config);

// Add a "Hello World" text watermark to the image.
$image = "image/watermark,text_SGVsbG8gV29ybGQ";

$options = array(
    OssClient::OSS_FILE_DOWNLOAD => $download_file,
    OssClient::OSS_PROCESS => $image);

// Save the processed image to your local machine.
$ossClient->getObject($bucket, $object, $options);                           

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

# Obtain access credentials from environment variables. Before you run the 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 general-purpose region ID.
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
# Specify the name of the source image. If the image is not in the root directory of the bucket, you must specify the full path, for example, exampledir/example.jpg.
key = 'src.jpg'
# Specify the name for the processed image.
new_pic = 'D:\\dest.jpg'

# Add a "Hello World" text watermark to the image.
image = 'image/watermark,text_SGVsbG8gV29ybGQ'
bucket.get_object_to_file(key, new_pic, process=image)

package main

import (
	"fmt"
	"os"

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

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// Obtain access credentials from environment variables. Before you run the 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.
	// Specify the endpoint for your bucket. In this example, the endpoint for the China (Hangzhou) region is used. Specify your actual endpoint.
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		HandleError(err)
	}

	// Specify the name of the bucket where the source image is stored. Example: examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}

	// Specify the name of the source image. If the image is not in the root directory of the bucket, you must specify the full path, for example, exampledir/example.jpg.
	sourceImageName := "src.jpg"
	// Specify a name for the processed image.
	targetImageName := "D://dest.jpg"
	// Add a "Hello World" text watermark to the image.
	image := "image/watermark,text_SGVsbG8gV29ybGQ"
	err = bucket.GetObjectToFile(sourceImageName, targetImageName, oss.Process(image))
	if err != nil {
		HandleError(err)
	}
}

GET /oss.jpg?x-oss-process=image/watermark,w_100 HTTP/1.1
Host: oss-example.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

Preguntas frecuentes

Uso de imágenes en línea o locales como marcas de agua

La imagen de marca de agua debe estar en el mismo bucket que la imagen de origen. Cargue primero las imágenes en línea o locales en el bucket.

Error "Font content is too large"

Las marcas de agua de texto están limitadas a 64 caracteres (cada carácter chino cuenta como tres). Si obtiene el error "font content is too large", acorte el texto. Example 1: Add a text watermark.

Fallo de marca de agua de imagen en objetos privados

Los objetos privados requieren una URL firmada. Incluya los parámetros IMG al generar la firma en lugar de agregarlos posteriormente. Generate a signed object URL that includes IMG parameters.

Color de fondo para marcas de agua de imagen

No.

Acceso a imágenes con una URL firmada

Los objetos privados requieren una URL firmada. Incluya los parámetros IMG al generar la firma en lugar de agregarlos posteriormente. Image Processing (Java SDK V1).

Organización vertical de marcas de agua

Sí. Utilice varias acciones watermark para organizar las marcas de agua verticalmente.

Ejemplo: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/watermark,text_SGVsbG8gV29ybGQ/watermark,text_SGVsbG8gV29ybGQy,y_60

Cambio dinámico del tamaño de las marcas de agua

IMG no admite el cambio dinámico del tamaño de las marcas de agua. Implemente lógica personalizada en su cliente o servidor para detectar las dimensiones de la imagen de origen y calcular el tamaño de la marca de agua antes de llamar a la API de OSS.

Número máximo de marcas de agua

Hasta tres marcas de agua. Para agregar más, envíe un ticket.