Use OSS image processing (IMG) to apply a Gaussian blur to images stored in Object Storage Service (OSS). You can blur the entire image or automatically target detected faces — useful for privacy protection, visual compositing, and display quality improvement.
Use cases
Privacy protection: Hide sensitive details such as license plate numbers or faces before publishing an image.
Layered image compositing: Smooth edges between layers in a multi-layer composite for a more polished result.
Low-resolution display: Soften pixelation artifacts when a low-resolution image is displayed on a high-definition screen.
Parameters
Action: blur
| Parameter | Required | Description | Valid values |
|---|---|---|---|
r | Yes | Blur radius. A higher value produces a stronger blur. | 1–50 |
s | Yes | Standard deviation of the Gaussian distribution. A higher value produces a stronger blur. | 1–50 |
g | No | Blur scope. Limits blurring to detected faces instead of the whole image. | face (largest face only), faces (all detected faces) |
p | No | Resize the blurred area as a percentage of the detected face size. Only applies when g is set. | 1–200 (%) |
Thegparameter requires the bucket to be bound to an Intelligent Media Management (IMM) project. Anonymous access is not supported when usingg. You must also have the required IMM permissions in OSS. For setup instructions, see Get started and Permissions.
Blur an image
Blur a public image using a URL
For images with a public-read or public-read-write access control list (ACL), append IMG parameters directly to the object URL. OSS processes the image in real time and returns the result — no SDK or API call needed.
Append ?x-oss-process=image/blur,r_10,s_10 to the object URL:
https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/blur,r_10,s_10| Source image | Processed image |
|---|---|
 |  |
https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg | https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/blur,r_10,s_10 |
Blur a private image using OSS SDKs
The examples below use image/blur,r_10,s_10 to blur the whole image and save the result to a local file. Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET as environment variables before running the code.
For other languages, see Overview.
Java
Java SDK 3.17.4 or later is required.
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 {
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
String region = "cn-hangzhou";
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
String bucketName = "examplebucket";
String objectName = "src.jpg";
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// Blur radius: 10, standard deviation: 10
String image = "image/blur,r_10,s_10";
GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
request.setProcess(image);
ossClient.getObject(request, new File("D:\\dest.jpg"));
} catch (OSSException oe) {
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("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}PHP
PHP SDK 2.7.0 or later is required.
<?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;
$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "examplebucket";
$object = "src.jpg";
$download_file = "D:\\dest.jpg";
$config = array(
"provider" => $provider,
"endpoint" => $endpoint,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"region" => "cn-hangzhou"
);
$ossClient = new OssClient($config);
// Blur radius: 10, standard deviation: 10
$image = "image/blur,r_10,s_10";
$options = array(
OssClient::OSS_FILE_DOWNLOAD => $download_file,
OssClient::OSS_PROCESS => $image);
$ossClient->getObject($bucket, $object, $options);Python
Python SDK 2.18.4 or later is required.
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
key = 'src.jpg'
new_pic = 'D:\\dest.jpg'
# Blur radius: 10, standard deviation: 10
image = 'image/blur,r_10,s_10'
bucket.get_object_to_file(key, new_pic, process=image)Go
Go SDK 3.0.2 or later is required.
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() {
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
HandleError(err)
}
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)
}
bucket, err := client.Bucket("examplebucket")
if err != nil {
HandleError(err)
}
// Blur radius: 10, standard deviation: 10
image := "image/blur,r_10,s_10"
err = bucket.GetObjectToFile("src.jpg", "D://dest.jpg", oss.Process(image))
if err != nil {
HandleError(err)
}
}Blur a private image using the OSS API
For custom integrations that call the REST API directly, include the blur parameters in a GetObject request. Sign the request using a V4 signature — see (Recommended) Include a V4 signature in the Authorization header.
GET /oss.jpg?x-oss-process=image/blur,r_10,s_10 HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValueFor the full GetObject specification, see GetObject.
For more implementation options, see IMG implementation modes.
Blur faces in an image
Face blurring uses OSS's integration with IMM to automatically detect faces. Before using the g parameter, bind the bucket to an IMM project — see Get started or AttachOSSBucket.
The examples below use OSS SDKs. For the API approach, use the same x-oss-process value in a GetObject request (see the pattern in the previous section).
Blur the largest face
Use g_face to detect and blur the largest face in the image.
Parameter string: image/blur,g_face,r_25,s_50
| Source image | Processed image |
|---|---|
|  |
Sample code
Blur all faces
Use g_faces to detect and blur all faces in the image.
Parameter string: image/blur,g_faces,r_25,s_50
| Source image | Processed image |
|---|---|
|  |
Sample code
Expand the blurred area beyond the face boundary
Use the p parameter to extend the blurred region beyond the detected face — useful when hair or surrounding context should also be hidden. The value is a percentage of the detected face size: p_200 expands the blurred area to twice the face size.
Largest face with expanded blur area
Parameter string: image/blur,g_face,p_200,r_25,s_50
| Source image | Processed image |
|---|---|
|  |
All faces with expanded blur area
Parameter string: image/blur,g_faces,p_200,r_25,s_50
| Source image | Processed image |
|---|---|
|  |
The SDK code follows the same pattern as the examples above — replace the image parameter string with the appropriate value. For example, in Java:
// Blur the largest face, expand the blurred area to 2x the face size
String image = "image/blur,g_face,p_200,r_25,s_50";
// Blur all faces, expand the blurred area to 2x the face size
// (declare in a separate scope or use a different variable name)
String image2 = "image/blur,g_faces,p_200,r_25,s_50";References
Combine OSS IMG blur with CSS filter: blur() to create layered visual effects in web pages. The following example applies IMG blur server-side and then adds a CSS blur on top for an additive effect:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Blur effect example</title>
<style>
.blurred {
filter: blur(5px);
}
.container {
position: relative;
width: 300px;
}
.text {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
color: white;
font-size: 24px;
}
</style>
</head>
<body>
<div class="container">
<img src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg" alt="Sample image" class="blurred">
<div class="text">Hello World</div>
</div>
<div>
<img src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image%2Fblur%2Cr_10%2Cs_10&spm=a2c4g.11186623.0.i12">
</div>
</body>
</html>