Object Storage Service:Document snapshots

Use cases

• Data backup: Periodically capture snapshots of key document pages in your OSS buckets.

• Key information extraction: Convert a specific page to an image to quickly extract or display content.

Limitations

• Document snapshots use synchronous processing only (the x-oss-process method).

• Maximum source document size: 20 MB.

• Supported input formats: pdf, xlsx, xls, docx, doc, pptx, ppt.

Prerequisites

Before you begin, make sure you have:

• An OSS bucket. See Create a bucket.

• The document uploaded to the bucket. See Upload objects.

• An Intelligent Media Management (IMM) project attached to the bucket, in the same region as the bucket. See Attach an IMM project.

Generate a document snapshot

Generate a signed URL with an x-oss-process parameter to retrieve a snapshot of any page. The URL is valid for the duration you set and can be opened directly in a browser.

All examples use the doc/snapshot action and generate a signed URL with a 3,600-second expiration. Replace the placeholder values with your actual bucket name, object name, and region.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
key = 'demo.docx'
expire_time = 3600

# Snapshot the second page of a .docx file and return it as a JPG.
process = 'doc/snapshot,target_jpg,source_docx,page_2'

url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)
print(url)

package com.aliyun.oss.demo;
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GeneratePresignedUrlRequest;
import java.net.URL;
import java.util.Date;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // Replace with the endpoint for your bucket region.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        String bucketName = "examplebucket";
        // If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
        String objectName = "demo.docx";
        String region = "cn-hangzhou";

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

        try {
            // Snapshot the second page of a .docx file and return it as a JPG.
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            Date expiration = new Date(new Date().getTime() + 3600 * 1000L);
            GeneratePresignedUrlRequest req = new GeneratePresignedUrlRequest(bucketName, objectName, HttpMethod.GET);
            req.setExpiration(expiration);
            req.setProcess(style);
            URL signedUrl = ossClient.generatePresignedUrl(req);
            System.out.println(signedUrl);
        } 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();
            }
        }
    }
}

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() {
    // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        HandleError(err)
    }

    clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
    clientOptions = append(clientOptions, oss.Region("cn-hangzhou"))
    clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
    client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", clientOptions...)
    if err != nil {
        HandleError(err)
    }

    bucket, err := client.Bucket("examplebucket")
    if err != nil {
        HandleError(err)
    }

    // If the object is not in the root directory, include the full path, e.g., exampledir/demo.docx.
    ossObjectName := "demo.docx"

    // Snapshot the second page of a .docx file and return it as a JPG. Max validity: 32,400 seconds.
    signedURL, err := bucket.SignURL(ossObjectName, oss.HTTPGet, 3600, oss.Process("doc/snapshot,target_jpg,source_docx,page_2"))
    if err != nil {
        HandleError(err)
    } else {
        fmt.Println(signedURL)
    }
}

const OSS = require("ali-oss");

async function generateSignatureUrl(fileName) {
  const client = await new OSS({
      // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // Replace oss-cn-hangzhou with the region where your bucket is located.
      region: 'oss-cn-hangzhou',
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {},
      queries: {
        // Snapshot the first page of a .docx file and return it as a JPG.
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1"
      }
  }, fileName);
}

generateSignatureUrl('demo.docx').then(url => {
  console.log('Generated signed URL:', url);
}).catch(err => {
  console.error('Error generating signed URL:', err);
});

<?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;

// Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$region = "cn-hangzhou";
$bucket = "examplebucket";
// If the object is not in the root directory, include the full path.
$object = "exampledir/demo.docx";

$config = array(
    "provider" => $provider,
    "endpoint" => $endpoint,
    "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
    "region" => $region
);
$ossClient = new OssClient($config);

$timeout = 3600;
$options = array(
    // Snapshot the first page of a .docx file and return it as a JPG.
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1"
);

$signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "GET", $options);
print("Signed URL: \n" . $signedUrl);

The generated signed URL looks like this:

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/demo.docx?x-oss-process=doc%2Fsnapshot%2Ctarget_jpg%2Csource_docx%2Cpage_1&x-oss-date=20250225T023122Z&x-oss-expires=3600&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI********************%2F20250225%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=c6620caa4dc160e5a70ee96b5bae08464edf7a41bb6d47432eda65474f68f26a

Open the URL in a browser to view the snapshot.

Parameters

Action: doc/snapshot

API reference

If your application has requirements beyond what the SDK supports, send REST API requests directly. For information on how to calculate the Authorization header, see Signature Version 4 (recommended).

GET /example.docx?x-oss-process=doc/snapshot HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue

GET /example?x-oss-process=doc/snapshot,target_jpg,source_docx,page_2 HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue

Permissions

An Alibaba Cloud account has full permissions by default. RAM users and RAM roles have no permissions by default — the account owner or an administrator must grant them using a RAM policy or a bucket policy.

Billing

Document snapshots incur charges for the following items. For pricing details, see OSS pricing and IMM billable items.