Perform intelligent document enrichment by using RESTful APIs and SDKs - Object Storage Service

Intelligent document enrichment uses AI to improve the style, fluency, and readability of existing documents. Submit a text payload through the OSS API and receive a polished version in return — either as a complete JSON response or as a stream of Server-Sent Events (SSE).

Prerequisites

Before you begin, ensure that you have:

An Intelligent Media Management (IMM) project mapped to your bucket. See Getting Started and AttachOSSBucket
The required permissions. See permissions

How it works

Submit a POST request to any object in your bucket using the x-oss-process header. The object name is a placeholder — OSS reads the text to enrich from the content parameter, not from the object itself.

The enriched text is returned in the response body. Choose between two response formats:

JSON mode (default): OSS returns the complete enriched text in a single JSON response.
SSE mode: OSS streams the enriched text as a sequence of Server-Sent Events (SSE) packets. Each packet contains the full output accumulated to that point. The stream ends when FinishReason changes from null to stop.

Constraints:

Supports synchronous processing only.
All requests must use the POST method.
Anonymous access is denied.

Enrich a document using the RESTful API

Request

Operation: doc/enrich

Method: POST

Path pattern:

POST /<object-name>?x-oss-process HTTP/1.1

Request parameters:

Parameter	Type	Required	Description
`content`	string	Yes	The document to enrich, encoded in URL-safe Base64. Maximum: 19,500 bytes.
`format`	string	No	Response format.<br>Default: `json` — returns the complete enriched text in a single response.<br>`event-stream` — SSE mode, streams enriched text as multiple packets. The stream terminates when `FinishReason` is `stop`.

Response parameters:

Parameter	Type	Description
`RequestId`	string	The request ID.
`Output`	struct	The output object. Contains `Text` and `FinishReason`.
`Output.Text`	string	The enriched text. In SSE mode, each packet contains the full output accumulated to that point, not just the delta.
`Output.FinishReason`	string	Task status. `null`: still running. `stop`: complete.

JSON mode example

The following example enriches a passage and receives the complete result in a single JSON response.

Request:

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/enrich,content_RXJuZXN0IEhlbWluZ3dheSdzICJUaGUgT2xkIE1hbiBhbmQgdGhlIFNlYSIgaXMgYSB0YWxlIG9mIGFuIG9sZCBmaXNoZXJtYW4sIFNhbnRpYWdvLCBhbmQgaGlzIGVwaWMgc3RydWdnbGUgdG8gY2F0Y2ggYSBnaWFudCBtYXJsaW4uIFRoaXMgc3RvcnkgaXMgYSBwcm9mb3VuZCBleHBsb3JhdGlvbiBvZiBodW1hbiBlbmR1cmFuY2UsIHBlcnNldmVyYW5jZSwgYW5kIHRoZSBiYXR0bGUgYWdhaW5zdCB0aGUgZm9yY2VzIG9mIG5hdHVyZS4gU2FudGlhZ28ncyB1bndhdmVyaW5nIGRldGVybWluYXRpb24gYW5kIGRpZ25pdHkgaW4gdGhlIGZhY2Ugb2YgYWR2ZXJzaXR5IHNlcnZlIGFzIGEgdGVzdGFtZW50IHRvIHRoZSBzdHJlbmd0aCBvZiB0aGUgaHVtYW4gc3Bpcml0Lg==

Response:

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Thu, 10 Aug 2023 11:09:00 GMT
Content-Type: application/json;charset=UTF-8
Connection: close
Vary: Accept-Encoding
x-oss-request-id: 6761403AAF96A1323085B4F6
x-oss-server-time: 2010
Content-Encoding: gzip

{
  "RequestId": "6761403AAF96A1323085B4F6",
  "Output": {
    "Text": "Ernest Hemingway's \"The Old Man and the Sea\" is a compelling narrative that centers around an elderly fisherman named Santiago...",
    "FinishReason": "stop"
  }
}

SSE mode example

Set format_event-stream in the request to receive the enriched text as a stream. Each SSE packet contains the full enriched text accumulated to that point. When FinishReason is stop, the stream is complete.

Request:

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/enrich,format_event-stream,content_5Zub5aSn5ZCN6JGX77yM5Y2z5Zub5aSn5bCP6K-05ZCN6JGX77yM5piv5oyH44CK5LiJ5Zu95ryU5LmJ44CL44CB44CK6KW_5ri46K6w44CL44CB44CK5rC05rWS5Lyg44CL44CB44CK57qi5qW85qKm44CLNOmDqOS4reWbveWPpOWFuOeroOWbnuWwj-ivtOOAgg==

Response:

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

id: 0
event: Result
data: {"RequestId":"67614140E3CA2838306217BE","Output":{"Text":"Er","FinishReason":"null"}}

id: 1
event: Result
data: {"RequestId":"67614140E3CA2838306217BE","Output":{"Text":"Ernest","FinishReason":"null"}}

id: 2
event: Result
data: {"RequestId":"67614140E3CA2838306217BE","Output":{"Text":"Ernest Hem","FinishReason":"null"}}

...

id: 94
event: Result
data: {"RequestId":"67614140E3CA2838306217BE","Output":{"Text":"Ernest Hemingway's \"The Old Man and the Sea\" is a poignant narrative...","FinishReason":"stop"}}

Each SSE packet contains the full enriched text accumulated to that point, not just the incremental delta. Read the final packet (where FinishReason is stop) to get the complete result.

Enrich a document using OSS SDKs

All SDK examples use the doc/enrich operation via the x-oss-process parameter. The object name (for example, example.docx) is a placeholder — OSS reads the text to enrich from the content parameter, encoded in URL-safe Base64.

Java

Requires OSS SDK for Java 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 {
        // Endpoint of the region where your bucket is located
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String region = "cn-hangzhou";

        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        String bucketName = "examplebucket";
        // Placeholder filename — OSS reads content from the content parameter, not from this object
        String key = "example.docx";

        // Encode the text to enrich in URL-safe Base64
        String content = "The text you want to enrich";
        String encodeContent = BinaryUtil.toBase64String(content.getBytes())
                .replaceAll("\\+", "-")
                .replaceAll("/", "_")
                .replaceAll("=", "");

        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/enrich,content_%s", encodeContent);

            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("Error Message: " + oe.getErrorMessage());
            System.out.println("Error Code: " + oe.getErrorCode());
            System.out.println("Request ID: " + oe.getRequestId());
        } catch (ClientException ce) {
            System.out.println("Error Message: " + ce.getMessage());
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

PHP

Requires OSS SDK for PHP 2.7.0 or later.

<?php
// Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET
$ak = getenv('OSS_ACCESS_KEY_ID');
$sk = getenv('OSS_ACCESS_KEY_SECRET');

$bucket = 'examplebucket';
// Placeholder filename — OSS reads content from the content parameter, not from this object
$objectKey = 'example.docx';

// Encode the text to enrich in URL-safe Base64
$txt = "The text you want to enrich";
$base64url = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($txt));
$body = sprintf("x-oss-process=doc/enrich,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, [
    '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);
} elseif ($httpcode == 200) {
    var_dump($response);
} else {
    echo "Error: HTTP code " . $httpcode;
}

Go

Requires OSS SDK for Go 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() {
    // Load credentials from environment variables OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, and OSS_SESSION_TOKEN
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    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, err := client.Bucket("examplebucket")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Encode the text to enrich in URL-safe Base64
    txt := "The text you want to enrich"
    data := fmt.Sprintf("x-oss-process=doc/enrich,content_%v",
        base64.URLEncoding.EncodeToString([]byte(txt)))

    // Placeholder filename — OSS reads content from the content parameter, not from this object
    params := map[string]interface{}{"x-oss-process": nil}
    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
    if err = json.Unmarshal(jsonData, &text); 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)
}