A pipeline chains multiple processing actions into a single API call, executing them sequentially in the order you specify. Separate actions with a vertical bar (|).
OSS pipelines support two processing modes:
| Mode | Query parameter | HTTP method | Supported operations |
|---|---|---|---|
| Synchronous | x-oss-process | GET | Image processing only |
| Asynchronous | x-oss-async-process | POST | Document processing (with sys/saveas and /notify only) |
How it works
Each action receives the output of the previous action as its input. Actions run left to right, in the order listed in the URL or request body.
Syntax
Synchronous processing
Append x-oss-process to the file URL and list actions separated by |:
<file URL>?x-oss-process=<action1>|<action2>Synchronous pipelines apply to image processing only. Online document preview and editing do not support pipelines.
Asynchronous processing
Use a POST request with x-oss-async-process as a query parameter. Pass the pipeline as the request body:
POST <file URL>?x-oss-async-process HTTP/1.1
Host: <Host header>
Date: <Date header>
Authorization: <Authorization header>
x-oss-async-process=<action1>|<action2>For asynchronous requests, onlysys/saveasand/notifycan be appended after the processing action.
Examples
Image processing
All image processing examples use synchronous GET requests with x-oss-process.
Example 1: Resize and add a text watermark
Resize the image to 300 px wide, then overlay the text watermark "Hello, Image Processing Service!":
https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/example.jpg@300h|watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQThe pipeline runs two actions in sequence:
| Step | Action | Effect |
|---|---|---|
| 1 | @300h | Resize to 300 px wide |
| 2 | watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ | Add text watermark (watermark=2) |
Example 2: Stack two watermarks
Add a text watermark to the bottom-right corner (p=9), then overlay an image watermark centered on the result (p=5):
https://oss-console-img-demo-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/example.jpg@watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&p=9|watermark=1&object=cGFuZGEucG5n&t=90&p=5The pipeline runs two actions in sequence:
| Step | Action | Effect |
|---|---|---|
| 1 | watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&p=9 | Text watermark "Hello, Image Service!" at bottom-right (p=9) |
| 2 | watermark=1&object=cGFuZGEucG5n&t=90&p=5 | Image watermark panda.png at 90% opacity, centered (p=5) |
Document processing
Document pipelines use asynchronous POST requests. The sys/saveas action saves the output to OSS, and /notify sends a notification to a Simple Message Queue (SMQ, formerly MNS) topic when processing completes.
Example: Convert a DOCX file to PNG and save the result
This pipeline converts example.docx to PNG, saves the output to oss://test-bucket/doc_images/, and notifies the SMQ topic doc_images.
POST /exmaple.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: OSS qn6q**************:77Dv****************
x-oss-async-process=doc/convert,target_png,source_docx|sys/saveas,b_dGVzdC1idWNrZXQ,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw/notify,topic_ZG9jX2ltYWdlcwThe pipeline runs two actions in sequence:
| Step | Action | Effect |
|---|---|---|
| 1 | doc/convert,target_png,source_docx | Convert DOCX to PNG |
| 2 | sys/saveas,b_dGVzdC1idWNrZXQ,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw/notify,topic_ZG9jX2ltYWdlcw | Save to oss://test-bucket/doc_images/ and notify SMQ topic doc_images |