使用SDK与API实现智能文档润色-对象存储-阿里云

支持使用 SDK 或 API 调用同步处理参数x-oss-process=doc/polish，对文档进行智能润色，优化措辞、结构与排版，使内容更清晰、易读。

前提条件

已创建 IMM Project 并将其与目标对象存储桶（Bucket）绑定。关于控制台和API如何绑定，请参见快速入门和AttachOSSBucket - 绑定对象存储桶。
已为访问身份授予 IMM 服务的相关权限。

参数说明

操作名称：doc/polish

具体参数如下表所示。

参数

类型

是否必须

描述

content

string

是

需要润色的文档内容，需经过URL安全的Base64编码。

说明

最大支持长度为19500字节。

format

string

否

指定返回数据的方式。取值：

json（默认值）：普通模式，会返回一个数据包，其中包含完整的请求结果。
event-stream：SSE模式，会收到多个数据包，其中每次都包含全量的数据。

返回参数如下表所示：

参数	类型	描述
RequestId	string	当次请求的Request ID。
Output	struct	输出的结果内容。子节点：Text, FinishReason
Text	string	本次请求的处理得到的结果内容。父节点：Output
FinishReason	string	当前生成结果的现状。取值： null：正在生成 stop：生成结束父节点：Output

使用SDK

以下仅列举常见SDK通过处理参数的方式使用智能文档润色的代码示例。如需使用其他SDK使用智能文档润色的代码示例，请参见以下常见SDK自行调整。

Java

要求使用3.17.4及以上版本的Java SDK。

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 {
        // yourEndpoint填写Bucket所在地域对应的Endpoint。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填写阿里云通用Region ID，例如cn-hangzhou。
        String region = "cn-hangzhou";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 指定Bucket名称。
        String bucketName = "examplebucket";
        // 指定文件名称，作为占位符使用。使用智能文档润色时，不读取该文件的内容。
        String key ="example.docx";
        // 指定待润色的文本内容。
        String content = "太阳系由太阳以及环绕其运行的天体构成，其中包括八大行星。这些行星与太阳的距离，从近到远依次是：水星、金星、地球、火星、木星、土星、天王星、海王星。";
        String encodeContent = BinaryUtil.toBase64String(content.getBytes()).replaceAll("\\+","-")
                .replaceAll("/","_").replaceAll("=","");

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源。
        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);
            // 构建智能文档润色处理指令。
            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及以上版本。

<?php
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$ak = getenv('OSS_ACCESS_KEY_ID');
$sk = getenv('OSS_ACCESS_KEY_SECRET');
// 指定Bucket名称，例如examplebucket。
$bucket = 'examplebucket';
// 指定文件名称，仅作为占位符使用。使用智能文档润色时，不读取该文件的内容。
$objectKey = 'example.docx';
// 指定待润色的文本内容。
$txt = "太阳系由太阳以及环绕其运行的天体构成，其中包括八大行星。这些行星与太阳的距离，从近到远依次是：水星、金星、地球、火星、木星、土星、天王星、海王星。";

$base64url = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($txt));
// 构建智能文档润色处理指令。
$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及以上版本。

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() {
	// 从环境变量中获取临时访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_SESSION_TOKEN。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// 创建OSSClient实例。
	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)
	}

	// 填写Bucket名称，例如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
        // 指定待润色的文本内容。
	txt := "太阳系由太阳以及环绕其运行的天体构成，其中包括八大行星。这些行星与太阳的距离，从近到远依次是：水星、金星、地球、火星、木星、土星、天王星、海王星。"
        // 构建智能文档润色处理指令。
	data := fmt.Sprintf("x-oss-process=doc/polish,content_%v", base64.URLEncoding.EncodeToString([]byte(txt)))
        // example.docx是Bucket中的某个文件，作为占位符使用。使用智能文档润色时，不读取该文件的内容。
	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

说明

进行文档智能润色时需要指定文件名称，但文件名称仅作为占位符使用。使用智能文档润色时，只识别content参数作为需要润色的文档内容。

普通模式

一次性返回完整的翻译结果。

请求示例

待处理文件：example.doc
待润色文本：“太阳系由太阳以及环绕其运行的天体构成，其中包括八大行星。这些行星与太阳的距离，从近到远依次是：水星、金星、地球、火星、木星、土星、天王星、海王星。”
返回结果方式：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

返回示例

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":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、地球、火星、木星、土星、天王星和海王星。",
        "FinishReason":"stop"
    }
}

SSE模式

以流式方式分段返回翻译结果。

请求示例

待处理文件：example.doc
待润色文本：“太阳系由太阳以及环绕其运行的天体构成，其中包括八大行星。这些行星与太阳的距离，从近到远依次是：水星、金星、地球、火星、木星、土星、天王星、海王星。”
返回结果方式：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

返回示例

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":"太阳","FinishReason":"null"}}

id: 1
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳","FinishReason":"null"}}

id: 2
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其","FinishReason":"null"}}

id: 3
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围","FinishReason":"null"}}

id: 4
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多","FinishReason":"null"}}

id: 5
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括","FinishReason":"null"}}

id: 6
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照","FinishReason":"null"}}

id: 7
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及","FinishReason":"null"}}

id: 8
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这","FinishReason":"null"}}

id: 9
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：","FinishReason":"null"}}

id: 10
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、","FinishReason":"null"}}

id: 11
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、地球、火星、木星","FinishReason":"null"}}

id: 12
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、地球、火星、木星、土星、天","FinishReason":"null"}}

id: 13
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、地球、火星、木星、土星、天王星和海王星","FinishReason":"null"}}

id: 14
event: Result
data: {"RequestId":"690487C31AFF653634FED36C","Output":{"Text":"太阳系由太阳及其周围环绕运行的众多天体组成，其中包括八大行星。按照距离太阳由近及远的顺序，这八大行星依次为：水星、金星、地球、火星、木星、土星、天王星和海王星。","FinishReason":"stop"}}

配额与限制

智能文档润色功能仅支持同步处理（x-oss-process处理方式）。
该接口需采用POST方式请求。
不支持匿名访问，所有请求必须经过签名授权。