Object Storage Service:Add watermarks

Scenarios

• Copyright protection: To prevent unauthorized replication or use of your images, you can watermark them to identify the copyright.

• Brand promotion: Enterprises and individuals can enhance brand visibility by adding watermarks featuring their logos or names to images, videos, and documents.

• Tamper prevention: Adding watermarks to official documents, certificates, and reports can increase the difficulty of tampering and reduce the risk of document forgery.

• Image plagiarism prevention: Images can be easily downloaded and republished by Internet users. You can add watermarks to images to show that they are copyrighted.

• Legal compliance: In certain situations, adding watermarks is necessary to fulfill legal compliance requirements when publishing specific legal or contract terms.

Usage notes

• You can use object URLs, OSS SDKs, or API operations to configure IMG parameters that are used to process images. In this example, object URLs are used. You can use object URLs to configure IMG parameters only for public-read images. If you want to configure IMG parameters for private images, use OSS SDKs or API operations. For more information, see IMG implementation modes.

• Only images stored in the current bucket can be used as watermarks. To use online or local images as watermarks, you must first upload the images to the current bucket.

• Only JPG, PNG, BMP, WebP, and TIFF images can be used as watermarks.

• You can add up to three different image watermarks to a single image. An image watermark cannot completely overlap another image watermark.

• Traditional Chinese characters cannot be used as text watermarks.

Parameters

Action: watermark

The following tables describe the parameters that you can configure when you add watermarks to images.

• Basic parameters

  Parameter	Required	Description	Value
  t	No	The opacity of the watermark.	[0,100] Default value: 100. The value 100 specifies that the watermark is opaque.
  g	No	The position of the watermark on the image. Default value: se. Valid values:	nw: upper left north: upper middle ne: upper right west: middle left center: center east: middle right sw: lower left south: lower middle se: lower right For the precise position that each value indicates, see the following reference position figure.
  x	No	The horizontal offset, which specifies the horizontal distance between the watermark and the image edge. This parameter takes effect only when the watermark is positioned on the upper left, middle left, lower left, upper right, middle right, or lower right of the image.	[0,4096] Default value: 10. Unit: pixel.
  y	No	The vertical offset, which specifies the vertical distance between the watermark and the image edge. This parameter takes effect only when the watermark is positioned on the upper left, upper middle, upper right, lower left, lower middle, or lower right of the image.	[0,4096] Default value: 10. Unit: pixel.
  voffset	No	The vertical offset from the middle line. When the watermark is positioned on the middle left, center, or middle right of the image, you can specify the vertical offset of the watermark along the middle line.	[-1000,1000] Default value: 0. Unit: pixel.
  fill	No	Specifies whether to tile the image watermarks or text watermarks across the image. Note If you want to add tiled watermarks, submit an application at Quota Center in the left-side navigation pane of the OSS console and submit an application for watermark titling.	1: tiles the watermarks across the image. 0: does not tile the watermarks across the image. This is the default value.
  padx	No	The horizontal spacing between watermarks when the watermarks are tiled across the image. This parameter is valid only when you set fill to 1.	[0,4096] Default value: 0. Unit: pixel.
  pady	No	The vertical spacing between watermarks when the watermarks are tiled across the image. This parameter is valid only when you set fill to 1.	[0,4096] Default value: 0. Unit: pixel.

  You can use parameters x, y, and voffset to adjust the position of a watermark on an image. You can also use these parameters to adjust the watermark layout when you add multiple watermarks to the image.

  The following figure shows the positions of watermarks based on coordinates.

• Image watermark parameters

  Parameter	Required	Description	Value
  image	Yes	The complete name of the image object that you want to use as a watermark. The object name must be Base64-encoded. For more information, see Encode watermark-related parameters. Note that the full path of the image watermark object must be a URL-safe, Base64-encoded string. For example, if the watermark image panda.png is located in the image directory, you should use Base64 encoding to convert the full path image/panda.png into a URL-safe string, which is aW1hZ2UvcGFuZGEucG5n. Note Only objects in the current bucket can be used as watermarks.	Base64-encoded string.

• Parameters for watermark image preprocessing

  You can preprocess watermark images by using image resizing, custom crop, indexed slice, rounded rectangle, and image rotation actions. In addition, you can include the P parameter to resize the watermark image.

  Parameter	Description	Value
  P	The percentage of the size of the image watermark relative to the original image size. For example, you set this parameter to 10. If the dimensions of the watermark image is 100 × 100 pixels, the size of the final image watermark is 10 × 10 pixels. If the dimensions of the watermark image is 200 × 200 pixels, the size of the final image watermark is 20 × 20 pixels.	[1,100]

• Text watermark parameters

  Parameter	Required	Description	Value
  text	Yes	The content of the text watermark. The text content must be Base64-encoded. For more information, see Encode watermark-related parameters.	A Chinese string before Base64-encoding cannot exceed 64 characters in length.
  type	No	The font of the text watermark. The font name must be Base64-encoded.	For more information about the supported fonts and the encoding results of the fonts, see Font types and encoding results. Default value: wqy-zenhei (encoding result: d3F5LXplbmhlaQ).
  color	No	The color of the text. The valid values for this parameter are RGB color values.	RGB color values. For example, the value 000000 specifies black, and the value FFFFFF specifies white. Default value: 000000.
  size	No	The size of the text.	(0,1000] Default value: 40. Unit: pixel.
  shadow	No	The opacity of the shadow for the text watermark.	[0,100] Default value: 0. The value 0 specifies that no shadows are added to the text.
  rotate	No	The degree by which the text is rotated clockwise.	[0,360] Default value: 0. The value 0 specifies that the text is not rotated.

  The following table describes the valid values of the type parameter and the encoding results of these values.

  Value	Description	Encoding result
  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

• Text-and-image watermark parameters

  Parameter	Required	Description	Value
  order	No	The order of the text watermark and image watermark.	0 and 1. 0 (default): The image watermark is on top of the text watermark. 1: The text watermark is on top of the image watermark.
  align	No	The alignment of the text watermark and image watermark.	0, 1, and 2. 0: Top alignment is applied to the text watermark and the image watermark. 1: Center alignment is applied to the text watermark and the image watermark. 2 (default): Bottom alignment is applied to the text watermark and the image watermark.
  interval	No	The spacing between the text watermark and image watermark.	[0,1000] Default value: 0. Unit: pixel.

Encode watermark-related parameters

When you add watermarks, you must use Base64 encoding to convert watermark-related parameters, such as the text, font of the text, and name of the watermark image, into URL-safe strings. You need to perform the following steps to complete encoding:

1. Encode watermark-related parameters in Base64.

2. Replace the following characters in the encoding result:

   • Replace plus signs (+) with hyphens (-).

   • Replace forward slashes (/) with underscores (_).

   • Omit all equal signs (=) at the end of the Base64-encoded content.

We recommend that you use the base64url encoder to encode watermark-related parameters.

Methods

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 of the region. In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region in which the bucket is located. 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 name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object that you want to process. Do not include the bucket name in the full path. 
        String objectName = "src.jpg";
        // Specify the full path to which you want to save the processed image. Example: D:\\localpath\\example-new.jpg. If a file that has the same name already exists in the path, the processed image overwrites the file. Otherwise, the processed image is saved in the path. 
        String pathName = "D:\\dest.jpg";

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

        try {
            // Add the text watermark "Hello World" to the image. 
            String image = "image/watermark,text_SGVsbG8gV29ybGQ";
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            request.setProcess(image);
            // Save the processed image as example-new.jpg to your local device. 
            // If you specify only the name of a local file such as example-new.jpg without specifying the local path of the file, the processed image is saved to the local path of the project to which the sample program belongs. 
            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 in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.jpg. Do not include the bucket name in the full path. 
$object = "src.jpg";
// Specify the full path to which you want to save the processed image. Example: D:\\localpath\\example-new.jpg. If a file that has the same name already exists in the path, the processed image overwrites the file. Otherwise, the processed image is saved in the path. 
// If you specify only the name of a local file such as example-new.jpg without specifying the local path of the file, the processed image is saved to the local path of the project to which the sample program belongs. 
$download_file = "D:\\dest.jpg";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. 
        "region" => "cn-hangzhou"
    );
$ossClient = new OssClient($config);

// Add the text watermark "Hello World" 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 device. 
$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 in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# Specify the ID of the Alibaba Cloud region in which the bucket is located. 
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
# Specify the name of the image to process. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: example/example.jpg. 
key = 'src.jpg'
# Specify the name of the processed image. 
new_pic = 'D:\\dest.jpg'

# Add the text watermark "Hello World" 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 of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.  
	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 in which the image to be watermarked is stored. Example: examplebucket. 
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}

	// Specify the name of the image to be watermarked. If the image is not stored in the root directory of the bucket, you must specify the full path of the image. Example: example/example.jpg. 
	sourceImageName := "src.jpg"
	// Specify the name of the processed image. 
	targetImageName := "D://dest.jpg"
	// Add the text watermark "Hello World" 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: OSS qn6q**************:77Dv****************

FAQ

How can I use online or local images as watermarks?

When IMG is used to add image watermarks to an image, make sure that the watermark images and the image to be watermarked are stored in the same bucket. To add online or local images as watermarks, you must first upload the images to the bucket that contains the image to be watermarked.

How can I resolve the "font content is too large" message that appears when I add a text watermark?

When you add a text watermark to an image by using OSS IMG parameters, the maximum allowed length for a text watermark is 64 English characters, with each Chinese character counting as three English characters. When the "font content is too large" message appears, we recommend that you shorten the text watermark. For more information, see Example 1: Add a text watermark.

What can I do if I fail to add an image watermark to a private object?

The URL of a private object must be signed. IMG parameters cannot be directly added to the end of a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see Generate a signed object URL that includes IMG parameters.

Can I configure a background color for an image watermark when I add the image watermark?

No, you cannot configure a background color for an image watermark.

How do I use a signed URL to access an image?

The URL of a private object must be signed. IMG parameters cannot be directly added to the end of a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see IMG.

Does OSS support the vertical arrangement of watermarks?

Yes, OSS supports the vertical arrangement of watermarks. If you want to arrange watermarks vertically, you can split the watermarking operation into multiple watermark actions and use multiple watermark actions to implement vertical watermark arrangement.

For example, you can use 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.

Does OSS support dynamic watermark sizing based on the size of the image to be watermarked?

No, OSS does not support dynamic watermark sizing based on the size of the image to be watermarked. You can write your logic to detect image size and adjust the size of text watermarks accordingly. You need to implement this logic on your client or server side before you call OSS operations to add watermarks.

How many watermarks can I add to an image at the same time?

You can add up to three watermarks to an image at the same time. If you want to add more than three watermarks to an image at the same time, submit a ticket.