You can use an SDK or an API to specify the synchronous processing parameter x-oss-process=doc/polish to intelligently polish documents. This feature optimizes the wording, structure, and layout of your documents to make them clearer and more readable.
Prerequisites
Create an Intelligent Media Management (IMM) project and attach it to the destination Object Storage Service (OSS) bucket. For more information, see Quick Start and AttachOSSBucket.
Grant the required permissions to the identity that you use to access IMM.
Parameters
Action: doc/polish
The following table describes the parameters.
Parameter | Type | Required | Description |
content | string | Yes | The content that you want to polish. The content must be encoded in URL-safe Base64. Note The content can be up to 19,500 bytes in length. |
format | string | No | The mode to return responses. Valid values:
|
The following table describes the response parameters.
Parameter | Type | Description |
RequestId | string | The request ID. |
Output | struct | The output. Child nodes: Text, FinishReason |
Text | string | The content of the response. Parent node: Output |
FinishReason | string | The status of the result. Valid values:
Parent node: Output |
Use SDKs
The following code provides examples of how to use common SDKs to intelligently polish documents by specifying processing parameters. To use other SDKs, adjust the code based on these examples.
Java
Java SDK 3.17.4 or later is required.
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
PHP SDK 2.7.0 or later is required.
<?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
Go SDK 3.0.2 or later is required.
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)
}
Use the API
Note
When you use intelligent document polishing, you must specify a filename. However, the filename is used only as a placeholder. The feature uses the value of the content parameter as the content to polish.
Normal mode
Returns the complete polished result at once.
Sample request
File to process: example.doc
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-c5L6d5qyh5piv77ya5rC05pif44CB6YeR5pif44CB5Zyw55CD44CB54Gr5pif44CB5pyo5pif44CB5Zyf5pif44CB5aSp546L5pif44CB5rW3546L5pif44CCSample 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
Returns the polished result in segments in a streaming manner.
Sample request
File to process: example.doc
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-c5L6d5qyh5piv77ya5rC05pif44CB6YeR5pif44CB5Zyw55CD44CB54Gr5pif44CB5pyo5pif44CB5Zyf5pif44CB5aSp546L5pif44CB5rW3546L5pif44CCSample 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: 3
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar system is composed of the","FinishReason":"null"}}
id: 4
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar system is composed of the Sun and numerous celestial","FinishReason":"null"}}
id: 5
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"The solar system is composed of the Sun and numerous celestial bodies that orbit it, including","FinishReason":"null"}}
id: 6
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","FinishReason":"null"}}
id: 7
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","FinishReason":"null"}}
id: 8
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","FinishReason":"null"}}
id: 9
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:","FinishReason":"null"}}
id: 10
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,","FinishReason":"null"}}
id: 11
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,","FinishReason":"null"}}
id: 12
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, Ura","FinishReason":"null"}}
id: 13
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":"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"}}Quotas and limits
Intelligent document polishing supports only synchronous processing (x-oss-process).
You must use the POST method to send requests.
Anonymous access is not supported. All requests must be signed and authorized.