When an asynchronous processing task completes, OSS returns only a task ID — not the result. To receive the result automatically instead of polling for it, add a notify parameter to your request. OSS then sends the result to a Simple Message Queue (SMQ) topic when the task finishes.
Limitations
Message notification is supported only for asynchronous processing.
Only SMQ topics are supported as the notification destination. SMQ was formerly known as MNS. For more information, see SMQ Quick Start.
The SMQ topic must be in the same region as the bucket.
Add a notification to an asynchronous request
Append the notify parameter to the x-oss-async-process value in your PostObject request.
Prerequisites
Before you begin, ensure that you have:
An OSS bucket
An SMQ topic in the same region as the bucket
The SMQ topic name (see How do I find my SMQ topic name?)
notify parameter
| Parameter | Required | Description |
|---|---|---|
topic | Yes | The URL-safe Base64-encoded name of the SMQ topic. For example, a topic named test is encoded as dGVzdA==. Use a Base64 URL encoding tool to encode the name. |
Request format
x-oss-async-process=<processing-action>|notify,topic_<base64-encoded-topic-name>Examples
All examples send the result to the SMQ topic named test-topic (Base64-encoded: dGVzdC10b3BpYw).
Convert a document and receive a notification
This example converts example.docx to PNG, saves the output to oss://test-bucket/doc_images/, and sends the result to the SMQ topic test-topic.
POST /example.docx?x-oss-async-process HTTP/1.1
Host: doc-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=doc/convert,target_png,source_docx|sys/saveas,b_dGVzdC1idWNrZXQ,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw/notify,topic_dGVzdC10b3BpYwTranscode a video and receive a notification
This example uses the style examplestyle to transcode example.avi, saves the output as oss://outbucket/outobjprefix.mp4, and sends the result to the SMQ topic test-topic.
POST /example.avi?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=style/examplestyle|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LnthdXRvZXh0fQ/notify,topic_dGVzdC10b3BpYwFor more information about using SMQ with REST APIs, see Python SDK version guide.
Message formats
The message format in SMQ depends on the processing operation.
| Feature | x-oss-process operation | Message format |
|---|---|---|
| Document processing | doc/convert | Sample MNS message for CreateOfficeConversionTask |
| ApsaraVideo Media Processing | video/convert, video/animation, video/sprite, video/snapshots, video/concat, audio/convert, audio/concat | Sample MNS message for CreateMediaConvertTask |
| File processing | pointcloud/compress | Sample MNS message for CreateCompressPointCloudTask |
| Image processing | image/deblindwatermark | Sample MNS message for CreateDecodeBlindWatermarkTask |
FAQ
How do I find my SMQ topic name?
Log on to the Simple Message Queue (SMQ), formerly MNS, console.
In the top navigation bar, select the same region as your OSS bucket.
In the left navigation pane, click Topic-based Model > Topic List.
Find the topic name in the list.
