Creates a document conversion task that converts documents, such as Word, PowerPoint, Excel, and PDF files, stored in Object Storage Service (OSS) into images, text files, or PDF files.
Operation description
-
Before you use this operation, make sure that you understand the billing methods and pricing of Intelligent Media Management (IMM).
Important The execution time of asynchronous tasks is not guaranteed. -
Supported input file formats:
Word processor documents (Word): doc, docx, wps, wpss, docm, dotm, dot, and dotx.
Presentation documents (PowerPoint): pptx, ppt, pot, potx, pps, ppsx, dps, dpt, pptm, potm, ppsm, and dpss.
Spreadsheet documents (Excel): xls, xlt, et, ett, xlsx, xltx, csv, xlsb, xlsm, xltm, and ets.
PDF documents: pdf.
-
Supported output file formats:
Images: png and jpg.
Text: txt.
PDF: pdf.
-
The maximum size of a single file is 200 MB. This limit cannot be changed.
-
If a file is large or its content is complex, the conversion may time out.
-
The number of requests per second is limited to 50 for a single user.
-
Task information is stored for only 7 days after a task starts. After this period, the information cannot be retrieved. You can promptly obtain task information using one of the following methods:
You can call the GetTask or ListTasks operation to obtain the returned
TaskIdand view the task information.You can activate Message Service (MNS) in the same region as IMM and configure a subscription to promptly receive task information notifications. For more information about the format of asynchronous notification messages, see Asynchronous notification message format. For more information about the MNS software development kit (SDK), see Receive and delete messages.
You can activate RocketMQ in the same region as IMM, and create a RocketMQ 4.0 instance, a topic, and a group to promptly receive task information notifications. For more information about the format of asynchronous notification messages, see Asynchronous notification message format. For more information about how to use RocketMQ, see Use an SDK for HTTP to send and receive normal messages.
You can activate and connect to EventBridge in the same region as IMM to promptly receive task information notifications. For more information, see Intelligent Media Management IMM events.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
imm:CreateOfficeConversionTask |
create |
*Project
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| ProjectName |
string |
Yes |
The project name. For more information about how to obtain the project name, see Create a project. |
test-project |
| SourceURI |
string |
No |
The storage address of the source data. The OSS address must be in the oss://${Bucket}/${Object} format. `${Bucket}` is the name of the OSS bucket that is in the same region as the current project. `${Object}` is the full path of the file, including the file name extension. |
oss://test-bucket/test-object |
| Sources |
array<object> |
No |
A list of input images. The images are converted in the order of their URIs in the list. (This parameter is not yet published. Do not use it.) |
oss://imm-test/test.pptx |
|
object |
No |
The information about an input image. |
||
| URI |
string |
No |
The OSS address of the source image. The OSS address must be in the oss://${Bucket}/${Object} format. ${Bucket} is the name of the OSS bucket that is in the same region as the current project. ${Object} is the full path of the file, including the file name extension. Supported image formats: jpg, jp2, png, tiff, webp, bmp, and svg. |
oss://examplebucket/sampleobject.jpg |
| Rotate |
integer |
No |
The rotation angle of the image. Valid values:
|
90 |
| TargetURI |
string |
No |
The template for the output address of the converted document. The address must be in the Note
Specify either this parameter or `TargetURIPrefix`. |
oss://examplebucket/outputDocument.pdf |
| TargetURIPrefix |
string |
No |
The prefix of the storage address for the output file after document conversion. The prefix must be in the Note
Specify either this parameter or `TargetURI`. |
oss://examplebucket/outputprefix/ |
| SourceType |
string |
No |
The extension type of the source data. By default, the type of the source data is determined by the extension of the OSS object. If the OSS object does not have an extension, you can set this parameter. Valid values:
|
doc |
| TargetType |
string |
Yes |
The type of the output file. Valid values:
|
png |
| UserData |
string |
No |
The custom information. This information is returned in the asynchronous notification message to help you associate the notification with your services. The value can be up to 2,048 bytes in length. |
{ "id": "test-id", "name": "test-name" } |
| Tags |
object |
No |
The custom tags. The value is a dictionary. You can use tags to search for tasks. |
{ "key": "value" } |
| StartPage |
integer |
No |
The start page for the document conversion. The default value is 1. Note
|
1 |
| EndPage |
integer |
No |
The end page for the document conversion. The default value is -1, which indicates that all pages from the start page to the last page are converted. Note
|
-1 |
| Password |
string |
No |
The password to open the document. Set this parameter if you want to convert a password-protected document. |
123456 |
| ScalePercentage |
integer |
No |
The scaling ratio of the document. Valid values: 20 to 199. The default value is 100, which indicates that the document is not scaled. Note
A value less than 100 indicates that the document is scaled down. A value greater than 100 indicates that the document is scaled up. |
100 |
| Quality |
integer |
No |
The quality of the converted file. Valid values: 0 to 100. A value of 0 indicates the lowest quality and the best performance. A value of 100 indicates the highest quality and the poorest performance. By default, the system sets an appropriate value based on the document content to balance quality and performance. |
60 |
| Pages |
string |
No |
The page numbers to convert. This parameter has a higher priority than the `StartPage` and `EndPage` parameters. The format is as follows:
|
1,2-4,7 |
| MaxSheetRow |
integer |
No |
The maximum number of rows to convert when you convert a spreadsheet document to images. By default, all rows are converted. Note
This parameter takes effect only when you set LongPicture to |
10 |
| MaxSheetColumn |
integer |
No |
The maximum number of columns to convert when you convert a spreadsheet document to images. By default, all columns are converted. Note
This parameter takes effect only when you set LongPicture to |
10 |
| SheetCount |
integer |
No |
The number of worksheets to convert to images in the spreadsheet document. By default, all worksheets are converted. |
1 |
| SheetIndex |
integer |
No |
The number of the worksheet to convert to images in the spreadsheet document. Valid values: 1 to the number of the last worksheet. The default value is 1. |
1 |
| FitToWidth |
boolean |
No |
When you convert a spreadsheet document to images or a PDF file, specifies whether to render all columns on a single image or PDF page. Valid values:
|
false |
| FitToHeight |
boolean |
No |
When you convert a spreadsheet document to images or a PDF file, specifies whether to render all rows on a single image or PDF page. Valid values:
|
false |
| FirstPage |
boolean |
No |
When you convert a spreadsheet document to images, specifies whether to return only the first image of the conversion result. The number of rows and columns in the image is the result of automatic splitting. Valid values:
Note
This parameter takes effect only if you set the LongPicture parameter to |
false |
| PaperSize |
string |
No |
The paper size for converting a spreadsheet document to images. The output image is similar to a printed page. Valid values:
Note
This parameter takes effect only when you use it with the FitToHeight and FitToWidth parameters. |
A4 |
| PaperHorizontal |
boolean |
No |
When you convert a spreadsheet document to images, specifies whether to place the paper horizontally. The output image is similar to a printed page. Valid values:
|
false |
| TrimPolicy | TrimPolicy |
No |
The trimming policy for spreadsheet conversion. For example, if a spreadsheet contains many empty rows and columns, a large amount of white space may be generated if no trimming policy is specified. |
|
| ShowComments |
boolean |
No |
When you convert a word processor document to images, specifies whether to show comments. Valid values:
|
false |
| LongPicture |
boolean |
No |
When you convert a document to images, specifies whether to convert it into a long image. Valid values:
Note
You can combine a maximum of 20 pages into a long image. If the number of pages exceeds this limit, the conversion task may fail. |
false |
| ImageDPI |
integer |
No |
The DPI of the output image. Valid values: 96 to 600. The default value is 96. |
96 |
| LongText |
boolean |
No |
When you convert a document to text, specifies whether to convert it into a long text file. Valid values:
|
false |
| HoldLineFeed |
boolean |
No |
When you convert a document to text, specifies whether to keep the line feeds in the document. Valid values:
|
false |
| CredentialConfig | CredentialConfig |
No |
If you do not have special requirements, leave this parameter empty. The chained authorization configuration. This parameter is not required. For more information, see Use chained authorization to access resources of other entities. |
|
| Notification | Notification |
No |
The message notification configuration. For more information, click Notification. For more information about the format of asynchronous notification messages, see Asynchronous notification message format. |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response for the asynchronous task. |
||
| RequestId |
string |
The request ID. |
FF3B7D81-66AE-47E0-BF69-157DCF18***** |
| TaskId |
string |
The task ID. |
formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd***** |
| EventId |
string |
The event ID. |
2C2-1I0EG57VR37J4rQ8oKG6C9***** |
Examples
Success response
JSON format
{
"RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF18*****",
"TaskId": "formatconvert-00bec802-073a-4b61-ba3b-39bc2fdd*****",
"EventId": "2C2-1I0EG57VR37J4rQ8oKG6C9*****"
}
Error codes
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.