The document format conversion feature of Intelligent Media Management (IMM) lets you process various document types. You can convert documents into the required output formats and save them to a specified OSS path for later use.
Scenarios
Online preview optimization: Users upload documents in various formats, such as PDF, Word, Excel, and PPT, to OSS. To allow users to preview these documents directly in a web or mobile application without downloading them, you can call the document conversion API from IMM. The documents are then converted into images suitable for online display.
Cross-platform compatibility: Support for file formats varies across different devices and operating systems. The document conversion service ensures that all users can view documents smoothly on any device.
Billing
Using the document format conversion service incurs the following fees:
Document processing fees: The document format conversion feature incurs document processing fees, which are charged on a per-call basis. For more information, see Document processing.
Traffic fees: Outbound traffic over the Internet is charged based on the size of the processed file. For more information, see Traffic fees.
Features
Supported file conversion types
The document format conversion feature supports the following conversions:
Input document type | Output document type | Description |
Word, Excel, PPT | Supports generating a PDF from images. | |
Word, Excel, PPT, PDF | PNG, JPEG | None |
Word, Excel, PPT | TXT | None |
JPEG | None |
Supported input file types
File type | File extension |
Word | doc, docx, wps, wpss, docm, dotm, dot, dotx |
PPT | pptx, ppt, pot, potx, pps, ppsx, dps, dpt, pptm, potm, ppsm, dpss |
Excel | xls, xlt, et, ett, xlsx, xltx, csv, xlsb, xlsm, xltm, ets |
Notes
The output content varies based on the output document type specified in the request. For information about sample outputs, see Sample outputs.
For JPEG and PNG output formats, the output content differs depending on whether the input document is a spreadsheet (Excel).
If the input document is a spreadsheet (Excel), multiple folders are generated based on the number of sheets in the spreadsheet. Then, multiple files are generated based on the preview page size.
If the input document is not a spreadsheet, such as a Word document or a PPT presentation, one file is generated for each page based on the document's style.
For PDF and TXT output formats, a single file is generated regardless of whether the input document is a spreadsheet (Excel).
You can specify the output path using the
TargetURIparameter, which supports variable rendering. For more information, see TargetURI templates. You can also specify the prefix of the output path using theTargetURIPrefixparameter. For information about the default output path, see Sample outputs.Files in .doc or .docx format can be converted only to PDF, image, or TXT formats. Conversion between .doc and .docx formats is not supported.
Usage notes
The time required for document format conversion depends on the document size, page count, and word count. A request is typically completed in seconds. However, large documents with many pages may take tens of seconds to process. To reduce application wait times, IMM provides the asynchronous CreateOfficeConversionTask API for document conversion.
Task information is stored for only seven days after a task starts. After this period, the information cannot be retrieved. You can obtain task information promptly in one of the following ways:
You can call the GetTask or ListTasks API to obtain the returned
TaskIdand view the task information.You can activate the MNS service in the same region as IMM and configure a subscription relationship to promptly receive task information notifications. For the format of asynchronous notification messages, see Asynchronous notification message format. For more information about the MNS SDK, see Step 4: Receive and delete messages.
You can activate the RocketMQ service in the same region as IMM, and create a RocketMQ 4.0 instance, topic, and group to promptly receive task information notifications. For the format of asynchronous notification messages, see Asynchronous notification message format. For more information about using RocketMQ, see Use an SDK for HTTP to send and receive normal messages.
You can activate and connect to the EventBridge service in the same region as IMM to receive real-time task information notifications. For more information, see Intelligent Media Management (IMM) events.
If the document definition is reduced after conversion, you can try adjusting the ImageDPI parameter when you call the CreateOfficeConversionTask API. A larger ImageDPI value results in a higher resolution and a clearer image.
Sample outputs
The following examples show the output content for different output document types. In these examples, the `TargetURIPrefix` is set to the OSS path oss://test-bucket/target/.
If the input document is a spreadsheet, the output is in the following format.
oss://test-bucket/target/{sheetname}_{sheetindex}_{sheetsubindex}.{autoext}If the input document is not a spreadsheet, the output is in the following format.
oss://test-bucket/target/{index}.{autoext}The following table describes the related parameters.
If the input file is a Word, PDF, or PPT file, this indicates the page number.
If the input file is an Excel file, this indicates `sheetindex_sheetsubindex`.
sheetindex: Starts from 1. Indicates the sheet number.
sheetsubindex: Starts from 1. A single sheet may be converted into multiple images. This indicates the index of the image for the current sheet.
Variable Name | Description | Example |
index | The output index, starting from 1. | 6_12 |
sheetname | If the input file is an Excel file, this indicates the name of the sheet. | sheet1 |
autoext | The extension of the output file. | jpg |
Asynchronous notification message format
If you set the message callback parameter in the request, you can obtain the number of converted documents (TargetFileCount) and custom information (UserData).
To use asynchronous message notifications, set the
Notificationcallback parameter when you make the request.The following table describes the parameters of the returned message.
{
"ProjectName": "immtest", // ProjectName is the project name.
"DatasetName": "", // DatasetName is the dataset name.
"RequestId": "A1DA7436-768B-061D-833C-****", // RequestId is the request ID.
"StartTime": "2023-01-04T05:03:40.928Z", // StartTime is the task start time.
"EndTime": "2023-01-04T05:03:41.444Z", // EndTime is the task end time.
"UserData": "test", // UserData is the custom user information.
"TaskType": "OfficeConversion", // TaskType is the task type.
"TaskId": "OfficeConversion-ed315cab-7736-4ad8-8c56-****", // TaskId is the conversion task ID.
"Status": "Succeeded", // Status is the conversion status.
"Code": "", // An empty Code indicates that the processing is successful.
"Message": "",// Message provides a description if the processing fails.
"TargetFileCount": 5 // TargetFileCount is the number of converted files.
}