All Products
Search
Document Center

Intelligent Media Management:CreateOfficeConversionTask

Last Updated:Jan 27, 2026

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:

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imm:CreateOfficeConversionTask

create

*Project

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}

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:

  • 0 (default)

  • 90

  • 180

  • 270

90

TargetURI

string

No

The template for the output address of the converted document.

The address must be in the oss://{bucket}/{tags.custom}/{dirname}/{barename}.{autoext} format. For more information, see TargetURI templates.

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 oss://${Bucket}/${Prefix}/ format. `${Bucket}` is the name of the OSS bucket that is in the same region as the current project. `${Prefix}` is the prefix of the storage address for the output file.

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:

  • 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

doc

TargetType

string

Yes

The type of the output file. Valid values:

  • png: Converts the document to PNG images.

  • jpg: Converts the document to JPG images.

  • pdf: Converts the document to a PDF file.

  • txt: Converts the document to a text-only file. This is mainly used to extract text content from the file. This option is supported only for presentation documents, word processor documents, and spreadsheet documents. When you convert a spreadsheet document, a single txt file is generated, and settings for sheet-related variables do not take effect.

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
  • If the source file is a spreadsheet, you must specify the worksheet number.

  • This parameter takes effect only when you convert the document to images. It does not take effect when you convert the document to a PDF file or a text file.

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
  • If the source file is a spreadsheet, you must specify the worksheet number (`SheetIndex`).

  • If the document has many pages, we recommend that you convert them in batches. Otherwise, the conversion may time out.

  • This parameter takes effect only when you convert the document to images. It does not take effect when you convert the document to a PDF file or a text file.

-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:

  • Separate multiple page numbers with commas (,), for example, 1,2.

  • Specify a range of consecutive pages with a hyphen (-), for example, 1,2-4,7.

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 true.

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 true.

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 (default): No. The content is rendered on multiple images or PDF pages.

  • true: Yes. The content is rendered on a single image or PDF page.

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 (default): No. The content is rendered on multiple images or PDF pages.

  • true: Yes. The content is rendered on a single image or PDF page.

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:

  • false (default): No. All images are returned.

  • true: Yes. Only the first image is returned. This is used to extract a thumbnail.

Note

This parameter takes effect only if you set the LongPicture parameter to true.

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:

  • A0

  • A2

  • A4 (default)

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 (default): No. The paper is placed vertically.

  • true: Yes. The paper is placed horizontally.

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 (default): No. Comments are not shown.

  • true: Yes. Comments are shown.

false

LongPicture

boolean

No

When you convert a document to images, specifies whether to convert it into a long image. Valid values:

  • false (default): No. The document is converted into multiple images.

  • true: Yes. The document is converted into a long image.

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 (default): No. Each page of the document is converted into a separate text file.

  • true: Yes. All content is placed in a single text file.

false

HoldLineFeed

boolean

No

When you convert a document to text, specifies whether to keep the line feeds in the document. Valid values:

  • false (default): No. Line feeds are not kept.

  • true: Yes. Line feeds are kept.

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.