Use intelligent document polishing with SDKs and API - Object Storage Service

Intelligent document polishing uses AI to refine the wording, structure, and layout of text content submitted through the OSS data processing interface (x-oss-process=doc/polish).

How it works

Submit text as a URL-safe Base64-encoded string in the content parameter. A filename is required in the request path but serves only as a placeholder -- the feature reads from content, not from the file.

Two response modes are available:

Normal mode (format=json): Returns the complete result in a single response. Default.
SSE mode (format=event-stream): Streams the result as Server-Sent Events (SSE). Each event contains the full accumulated text up to that point.

Prerequisites

Before you begin, ensure that you have:

An Intelligent Media Management (IMM) project attached to the target Object Storage Service (OSS) bucket. See Quick Start and AttachOSSBucket
The required permissions granted to the identity accessing IMM

Parameters

Action: doc/polish

Request parameters

Parameter	Type	Required	Description
`content`	string	Yes	Text to polish, encoded in URL-safe Base64. Maximum length: 19,500 bytes.
`format`	string	No	Response mode. Valid values: `json` (default) -- returns the complete result in one response. `event-stream` -- streams multiple events where each contains the full accumulated text.

Response parameters

Parameter	Type	Description
`RequestId`	string	Request ID.
`Output`	struct	Output object. Child nodes: `Text`, `FinishReason`.
`Output.Text`	string	Polished text content.
`Output.FinishReason`	string	Result status. `null` (string): processing in progress. `stop`: processing complete.

SDK examples

Adapt these examples for other supported SDKs.

Java

Requires Java SDK 3.17.4 or later.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.common.utils.BinaryUtil;
import com.aliyun.oss.common.utils.IOUtils;
import com.aliyun.oss.model.GenericResult;
import com.aliyun.oss.model.ProcessObjectRequest;

import java.io.IOException;
import java.util.Formatter;

public class Demo {
    public static void main(String[] args) throws ClientException, com.aliyuncs.exceptions.ClientException {
        // Set endpoint to the endpoint of the region where the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the ID of the Alibaba Cloud region, for example, cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the filename, which is used only as a placeholder. When you use intelligent document polishing, the content of this file is not read.
        String key ="example.docx";
        // Specify the text to polish.
        String content = "The solar system consists of the Sun and the celestial bodies that orbit it, including eight planets. In order of their distance from the Sun, from nearest to farthest, these planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune.";
        String encodeContent = BinaryUtil.toBase64String(content.getBytes()).replaceAll("\\+","-")
                .replaceAll("/","_").replaceAll("=","");

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer used, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {

            StringBuilder sbStyle = new StringBuilder();
            Formatter styleFormatter = new Formatter(sbStyle);
            // Build the intelligent document polishing instruction.
            styleFormatter.format("doc/polish,content_%s",
                    encodeContent);
            System.out.println(sbStyle.toString());
            ProcessObjectRequest request = new ProcessObjectRequest(bucketName, key, sbStyle.toString());
            GenericResult processResult = ossClient.processObject(request);
            String json = IOUtils.readStreamAsString(processResult.getResponse().getContent(), "UTF-8");
            processResult.getResponse().getContent().close();
            System.out.println(json);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            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("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

PHP

Requires PHP SDK 2.7.0 or later.

<?php
// Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
$ak = getenv('OSS_ACCESS_KEY_ID');
$sk = getenv('OSS_ACCESS_KEY_SECRET');
// Specify the bucket name, for example, examplebucket.
$bucket = 'examplebucket';
// Specify the filename, which is used only as a placeholder. When you use intelligent document polishing, the content of this file is not read.
$objectKey = 'example.docx';
// Specify the text to polish.
$txt = "The solar system consists of the Sun and the celestial bodies that orbit it, including eight planets. In order of their distance from the Sun, from nearest to farthest, these planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune.";

$base64url = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($txt));
// Build the intelligent document polishing instruction.
$body = sprintf("x-oss-process=doc/polish,content_%s", $base64url);

$httpVerb = 'POST';
$contentMd5 = base64_encode(md5($body, true));
$contentType = '';
$date = gmdate('D, d M Y H:i:s T');
$stringToSign = $httpVerb . "\n" . $contentMd5 . "\n" . $contentType . "\n" . $date . "\n" . "/{$bucket}/{$objectKey}?x-oss-process";
$signature = base64_encode(hash_hmac('sha1', $stringToSign, $sk, true));

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://{$bucket}.oss-cn-hangzhou.aliyuncs.com/{$objectKey}?x-oss-process");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Date: ' . $date,
    'Authorization: OSS ' . $ak . ':' . $signature,
    'Content-Type: ' . $contentType,
    'Content-Md5:' . $contentMd5,
));
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$response = curl_exec($ch);

$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
    echo "Error: " . curl_error($ch);
} else {
    if ($httpcode == 200) {
        var_dump($response);
    } else {
        echo "Error: HTTP code " . $httpcode;
    }
}

Go

Requires Go SDK 3.0.2 or later.

package main

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"os"
	"strings"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

type TextData struct {
	RequestId string `json:"RequestId"`
	Output    struct {
		Text         string `json:"Text"`
		FinishReason string `json:"FinishReason"`
	} `json:"Output"`
}

func main() {
	// Obtain temporary access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, and OSS_SESSION_TOKEN environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Create an OSSClient instance.
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	params := make(map[string]interface{})
	params["x-oss-process"] = nil
        // Specify the text to polish.
	txt := "The solar system consists of the Sun and the celestial bodies that orbit it, including eight planets. In order of their distance from the Sun, from nearest to farthest, these planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
        // Build the intelligent document polishing instruction.
	data := fmt.Sprintf("x-oss-process=doc/polish,content_%v", base64.URLEncoding.EncodeToString([]byte(txt)))
        // example.docx is a file in the bucket and is used as a placeholder. When you use intelligent document polishing, the content of this file is not read.
	response, err := bucket.Do("POST", "example.docx", params, nil, strings.NewReader(data), nil)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	defer response.Body.Close()
	jsonData, err := io.ReadAll(response.Body)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	var text TextData
	err = json.Unmarshal(jsonData, &text)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Printf("RequestId:%v\n", text.RequestId)
	fmt.Printf("Text:%v\n", text.Output.Text)
	fmt.Printf("FinishReason:%v\n", text.Output.FinishReason)
}

API reference

Note

A filename must be specified in the request path, but it serves only as a placeholder. The feature reads from the content parameter, not from the file.

Normal mode

Returns the complete polished result in a single response.

Sample request

File: example.doc (placeholder)
Text to polish: "The solar system consists of the Sun and the celestial bodies that orbit it, including eight planets. In order of their distance from the Sun, from nearest to farthest, these planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
Response format: json

POST /example.doc?x-oss-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-process=doc/polish,content_5aSq6Ziz57O755Sx5aSq6Ziz5Lul5Y-K546v57uV5YW26L-Q6KGM55qE5aSp5L2T5p6E5oiQ77yM5YW25Lit5YyF5ous5YWr5aSn6KGM5pif44CC6L-Z5Lqb6KGM5pif5LiO5aSq6Ziz55qE6Led56a777yM5LuO6L-R5Yiw6L-c5L6d5qyh5piv77ya5rC05pif44CB6YeR5pif44CB5Zyw55CD44CB54Gr5pif44CB5pyo5pif44CB5Zyf5pif44CB5aSp546L5pif44CB5rW3546L5pif44CC

Sample response

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Thu, 10 Aug 2023 11:56:21 GMT
Content-Type: application/json;charset=UTF-8
Connection: close
Vary: Accept-Encoding
x-oss-request-id: 6597BEF94479D8313302D71D
x-oss-server-time: 2106
Content-Encoding: gzip

{
    "RequestId":"6597BEF94479D8313302D71D",
    "Output":{
        "Text":"The solar system is composed of the Sun and numerous celestial bodies that orbit it, including eight major planets. In order of their distance from the Sun, from nearest to farthest, these eight planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune.",
        "FinishReason":"stop"
    }
}

SSE mode

Streams the polished result as Server-Sent Events. Each event contains the full accumulated text up to that point.

Sample request

File: example.doc (placeholder)
Text to polish: "The solar system consists of the Sun and the celestial bodies that orbit it, including eight planets. In order of their distance from the Sun, from nearest to farthest, these planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
Response format: event-stream

POST /example.doc?x-oss-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-process=doc/polish,format_event-stream,content_5aSq6Ziz57O755Sx5aSq6Ziz5Lul5Y-K546v57uV5YW26L-Q6KGM55qE5aSp5L2T5p6E5oiQ77yM5YW25Lit5YyF5ous5YWr5aSn6KGM5pif44CC6L-Z5Lqb6KGM5pif5LiO5aSq6Ziz55qE6Led56a777yM5LuO6L-R5Yiw6L-c5L6d5qyh5piv77ya5rC05pif44CB6YeR5pif44CB5Zyw55CD44CB54Gr5pif44CB5pyo5pif44CB5Zyf5pif44CB5aSp546L5pif44CB5rW3546L5pif44CC

Sample response

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Thu, 10 Aug 2023 11:55:03 GMT
Content-Type: text/event-stream;charset=UTF-8
Transfer-Encoding: chunked
Connection: close
x-oss-request-id: 690487C31AFF653634FED36C
x-oss-server-time: 2356


id: 0
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The","FinishReason":"null"}}

id: 1
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar","FinishReason":"null"}}

id: 2
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar system is","FinishReason":"null"}}

...

id: 14
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar system is composed of the Sun and numerous celestial bodies that orbit it, including eight major planets. In order of their distance from the Sun, from nearest to farthest, these eight planets are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune.","FinishReason":"stop"}}

In SSE mode, FinishReason is "null" (string) while processing is in progress and changes to "stop" on the final event.

Limits

Only synchronous processing via the x-oss-process parameter is supported. Asynchronous processing is not available.
All requests must use the POST method.
Anonymous access is not supported. Sign and authorize all requests.