Use variables in output paths to generate unique names for processed objects dynamically. Without variables, multiple processing tasks writing to the same output path overwrite each other — a common issue in batch jobs and trigger-driven workflows where many source objects are processed simultaneously.
For example, set the output path for a video frame extraction task to oss://test-bucket/{dirname}/{barename}_output.{autoext}. OSS resolves the variables at processing time, so each source object produces a uniquely named output.
Where to use variables
Variables work in the following contexts:
| Context | Where to specify variables |
|---|---|
| Tasks (OSS console) | Output path field |
| Batch processing (OSS console) | Output path field for processed objects |
| Trigger (OSS console) | Output path field when creating the trigger |
| `sys/saveas` parameter (API) | b and o options |
| `TargetURI` parameter (API) | Full output path for data processing tasks |
Console examples
Tasks: Convert a document to JPG images. Set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. During the task, {autoext} resolves to jpg, and processed objects are saved to oss://test-bucket/output/<source object directory>/<source object name>/<image serial number>.jpg.
Batch processing: Capture PNG frames from multiple videos at once. Set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. {autoext} resolves to png, and frames are saved to oss://test-bucket/output/<source video directory>/<source video name>/<frame sequence number>.png.
Trigger: Create a trigger to convert documents to JPG images. Set the output path to oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}. Each new object added to the source bucket triggers a task, and output is saved to oss://test-bucket/output/<source object directory>/<source object name>/<image sequence number>.jpg.
API examples
`sys/saveas` parameter: The b and o options support variables. To convert pages 1–10 of example.docx to PNG images, set sys/saveas to:
b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZwWhere:
e2J1Y2tldH0is the Base64-encoded value of{bucket}— saves to the same bucket as the source objectZG9jX2ltYWdlcy97aW5kZXh9LnBuZwis the Base64-encoded value ofdoc_images/{index}.png— output paths aredoc_images/<page number>.png
`TargetURI` parameter: When calling CreateOfficeConversionTask, set TargetURI to the full output path including file extension. Variables are supported. Example: oss://test-bucket/output/{dirname}/{barename}/{index}.jpg.
Usage notes
For batch processing jobs and trigger tasks: if the output path does not end with
/, include at least one variable in the object name. Otherwise, processed objects overwrite each other.For data processing tasks: the output path cannot end with
/, but can end with a variable.
Available variables
Variables resolve based on the source object and the time the request was submitted. The following table shows which variables are available for each processing type:
| Variable | Time-of-request | IMG | Document conversion | Media processing |
|---|---|---|---|---|
t_year | Yes | — | — | — |
t_mon | Yes | — | — | — |
t_day | Yes | — | — | — |
t_hour | Yes | — | — | — |
t_min | Yes | — | — | — |
t_sec | Yes | — | — | — |
bucket | — | Yes | — | — |
key | — | Yes | — | — |
dirname | — | Yes | — | — |
barename | — | Yes | — | — |
basename | — | Yes | — | — |
ext | — | Yes | — | — |
year | — | Yes | — | — |
mon | — | Yes | — | — |
day | — | Yes | — | — |
hour | — | Yes | — | — |
min | — | Yes | — | — |
sec | — | Yes | — | — |
autoext | — | — | Yes | Yes |
index | — | — | Yes (page number / sheet subindex) | Yes (segment sequence) |
sheetname | — | — | Yes | — |
sheetindex | — | — | Yes | — |
sheetsubindex | — | — | Yes | — |
streamindex | — | — | — | Yes |
resolution | — | — | — | Yes |
Time-of-request variables
These variables resolve to the point in time when the request was submitted, whether synchronously or asynchronously.
Reference: Request submitted at 2022-09-01T02:06:57.798Z
| Variable | Description | Format | Example |
|---|---|---|---|
t_year | Year the request was submitted | yyyy | 2022 |
t_mon | Month the request was submitted | mm | 09 |
t_day | Day the request was submitted | dd | 01 |
t_hour | Hour the request was submitted | HH | 02 |
t_min | Minute the request was submitted | MM | 06 |
t_sec | Second the request was submitted | SS | 57 |
Applies to: Data processing tasks (synchronous and asynchronous requests).
IMG variables
These variables resolve based on the source object's path and upload time.
Reference: Source object oss://test-bucket/path1/path2/name.png, uploaded 2022-04-22 14:38:25
| Variable | Description | Example |
|---|---|---|
bucket | Name of the source bucket | test-bucket |
key | Full name of the source object, including path and extension | path1/path2/name.png |
dirname | Directory path of the source object | path1/path2 |
barename | Name of the source object, excluding extension | name |
basename | Name of the source object, including extension | name.png |
ext | Extension of the source object, derived from its MIME type or the key variable | png |
year | Year the source object was uploaded | 2022 |
mon | Month the source object was uploaded | 04 |
day | Day the source object was uploaded | 22 |
hour | Hour the source object was uploaded | 14 |
min | Minute the source object was uploaded | 38 |
sec | Second the source object was uploaded | 25 |
Do not set the output object name equal to the source object name using key, dirname, barename, or basename alone — this overwrites the source object or causes the processing task to loop during batch processing.
Applies to: IMG processing tasks.
Example: For a source object at oss://test-bucket/videos/2024/clip.mp4, the path oss://output-bucket/{dirname}/{barename}_processed.{ext} resolves to oss://output-bucket/videos/2024/clip_processed.mp4.
Document conversion variables
These variables resolve based on the document structure (page number, sheet name) of the source object.
Reference: Excel object with one sheet named sheet1, converted to JPG
| Variable | Description | Example |
|---|---|---|
autoext | Extension of the processed object | png |
index | Sequence index of the content. For Word, PDF, and PPT objects: page number. For Excel objects: sheetindex_sheetsubindex. Row numbering starts at 1. | Word/PDF/PPT: 1_1; Excel: 1_1 |
sheetname | Name of the sheet in the Excel object | sheet1 |
sheetindex | Index of the sheet in the Excel object. Minimum value: 1. | 1 |
sheetsubindex | Subindex of the sheet in the Excel object. Minimum value: 1. | 1 |
Applies to: Document conversion tasks (Word, PDF, PPT, Excel).
Example: For an output path oss://test-bucket/output/{dirname}/{barename}/{index}.{autoext}, converting page 3 of reports/Q1.docx produces oss://test-bucket/output/reports/Q1/3_1.jpg (where {autoext} resolves to jpg).
Media processing variables
These variables resolve based on the transcoding output properties.
Reference: Multipart transcoding of video.mp4 to TS format at 1920x1080
| Variable | Description | Example |
|---|---|---|
autoext | Extension of the processed object | ts |
index | Index that specifies the sequence of the content in the source object. Row numbering starts at 1. Used for multipart transcoding and snapshot capture. | 1 |
streamindex | ID of the audio or video stream. Minimum value: 0. | 0 |
resolution | Resolution of the processed object. Available for video only. | 1920x1080 |
Applies to: Media processing tasks (video transcoding, multipart transcoding, snapshot capture).
Example: For an output path oss://test-bucket/output/{barename}_{resolution}_{index}.{autoext}, transcoding segment 2 of video.mp4 at 1920x1080 produces oss://test-bucket/output/video_1920x1080_2.ts.
Theautoextandindexvariables appear in both document conversion and media processing, butindexhas different semantics in each context: for document conversion, it represents the page number or sheet subindex; for media processing, it represents the output segment sequence number.
Use the OSS API
For high-customization workflows, call RESTful APIs directly. Direct API calls require you to include signature calculation in your code.
Specify processing parameters or style parameters in a PostObject request to process a source object. For more information, see sys/saveas.
All examples below use the x-oss-async-process header to submit asynchronous processing tasks. The b and o options in sys/saveas accept Base64-encoded variable expressions.
Example 1: Document conversion
Convert pages 1–10 of example.docx to PNG images and save them to the source bucket under doc_images/<page number>.png.
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: OSS qn6q**************:77Dv****************
x-oss-async-process=doc/convert,pages_MS0xMA,target_png,source_docx|sys/saveas,b_e2J1Y2tldH0,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZwParameters:
| Parameter | Value | Description |
|---|---|---|
pages_MS0xMA | Base64(1 to 10) | Converts pages 1–10 |
target_png | — | Output format: PNG |
source_docx | — | Source format: DOCX |
b_e2J1Y2tldH0 | Base64({bucket}) | Saves to the same bucket as the source object |
o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw | Base64(doc_images/{index}.png) | Output path pattern: doc_images/<page number>.png |
Example 2: Video transcoding
Transcode example.avi to MP4 with H.265 encoding at 1920x1080, and save the output to the source bucket as output.<autoext>.
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: OSS qn6q**************:77Dv****************
x-oss-async-process=video/convert,f_mp4,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1|sys/saveas,b_e2J1Y2tldH0,o_b3V0cHV0LnthdXRvZXh0fQParameters:
| Parameter | Value | Description |
|---|---|---|
f_mp4 | — | Output container format: MP4 |
vcodec_h265 | — | Video encoding: H.265 |
s_1920x1080 | — | Resolution: 1920x1080 |
vb_2000000 | — | Video bitrate: 2 Mbit/s |
fps_30 | — | Frame rate: 30 fps |
acodec_aac | — | Audio encoding format: AAC |
ab_100000 | — | Audio bitrate: 100 Kbit/s |
sn_1 | — | Disables the subtitle stream |
b_e2J1Y2tldH0 | Base64({bucket}) | Saves to the same bucket as the source object |
o_b3V0cHV0LnthdXRvZXh0fQ | Base64(output.{autoext}) | Output path: output.mp4 (extension resolved from {autoext}) |