Document conversion

Uploadcare can convert documents from all popular formats via REST API. For example, you can upload PDF and generate its thumbnail with PDF to PNG first page conversion, bring different office formats to web-friendly PDFs, or make previews for artists’ PSD/AI files.

We support conversion between many different file formats. All possible input and output formats can be seen in the tables below.

How it works

Document conversion works asynchronously through the REST API, unlike the image processing operations performed on the fly.

It generates encoded output as a separate file while the original file remains intact.

1. Start a processing job via REST API. Send an input file UUID with necessary processing operations.
2. Wait until the processing job status becomes finished.
3. The processed file can be addressed via its new UUID, as well as an URL with operations provided in a processing request.

Conversion formats info

You can determine the file format and possible conversion formats using a request:

https://api.uploadcare.com/convert/document/:UUID/

$
curl -X GET \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    "https://api.uploadcare.com/convert/document/:UUID/"

Get $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY from API keys.

File info in response:

1
{
2
    "format": {
3
        "name": "jpg",
4
        "conversion_formats": [{
5
            "name": "avif"
6
        },
7
        {
8
            "name": "bmp"
9
        },
10
        {
11
            "name": "gif"
12
        },
13
        {
14
            "name": "ico"
15
        },
16
        {
17
            "name": "pcx"
18
        },
19
        {
20
            "name": "pdf"
21
        },
22
        {
23
            "name": "png"
24
        },
25
        {
26
            "name": "ps"
27
        },
28
        {
29
            "name": "svg"
30
        },
31
        {
32
            "name": "tga"
33
        },
34
        {
35
            "name": "thumbnail"
36
        },
37
        {
38
            "name": "tiff"
39
        },
40
        {
41
            "name": "wbmp"
42
        },
43
        {
44
            "name": "webp"
45
        }]
46
    }
47
}

Check out API reference for GET /convert/document/:UUID/.

Processing job

The endpoint for document conversion request is:

https://api.uploadcare.com/convert/document/

$
curl -X POST \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    -d '{"paths": [":UUID/document/-/format/:target_format/"], "store": "1"}' \
>
    "https://api.uploadcare.com/convert/document/"

Project pointed with $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY should have enabled Document conversion feature. The :UUID of the source file to convert should belong to the project.

Input file identifiers should be formatted with UUID followed by /document/ (please note, this is not operation, so there shouldn’t be /-/ between them) and ended by operations separated by /-/:

1
https://ucarecdn.com/:uuid/document/-/format/:target_format/

The following operations are available for the conversion job:

• /format/:target_format/ — defines the target conversion format.
• /page/:number/ — converts a single page of a multi-page document to either jpg or png. This method won’t work for other target formats. :number — is a one-based number for a page to convert.

Operations can be omitted; the document will then be delivered as a pdf.

Check out detailed API reference for POST /convert/document/.

Webhook event

To get the job result, you need to enable file.uploaded in the Webhook section of the dashboard.

After completing the processing job, the webhook will be sent to the endpoint you specified in the webhook settings.

File information in response:

1
"initiator": {
2
      "type": "addon",
3
      "detail": {
4
          "addon_name": "zamzar_convert_document",
5
          "request_id": "80c78d01-f8b6-432a-bb1f-b707f86e0106",
6
          "source_file_uuid": ":UUID"
7
      }
8
   }
9
  "hook": {
10
    ...
11
    "event": "file.uploaded",
12
    "is_active": true,
13
    "version": "0.7",
14
    "created_at": "2023-10-26T09:32:40.114516Z",
15
    "updated_at": "2023-10-26T09:32:40.114516Z"
16
  },
17
  "data": {
18
    "content_info": {
19
      "mime": {
20
        "mime": "text/plain",
21
        "type": "text",
22
        "subtype": "plain"
23
      }
24
    },
25
    "uuid": ":new_UUID",
26
    "is_image": false,
27
    "is_ready": true,
28
    "metadata": {},
29
    "appdata": {
30
      "uc_clamav_virus_scan": {
31
        "data": {
32
          "infected": false
33
        },
34
        "version": "1.0.1",
35
        "datetime_created": "2023-10-26T17:29:30.331Z",
36
        "datetime_updated": "2023-10-26T17:29:30.331Z"
37
       }
38
     }
39
  }

After receiving source_file_uuid, you can make a GET request for the original file and get all the variations from there:

1
"uuid": ":UUID", "variations": {
2
    "document/-/format/txt/": ":new_UUID"
3
}

Job status

If your application does not have a backend or uses a mobile version, you can submit the request yourself.

As a request result, you immediately receive an UUID of the new file. But it cannot be accessible due to that conversion takes time. Once you get a processing job result, you can get a processing job status using :token.

$
curl -X GET \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    "https://api.uploadcare.com/convert/document/status/:token/"

Check out detailed API reference for GET /convert/document/status/:token/.

Job result

The processed document becomes addressable via both a new UUID and a CDN URL you provided in the request:

1
https://ucarecdn.com/:new_uuid/
2
https://ucarecdn.com/:original_uuid/document/-/:operation/:parameters/

Applying the same set of conversion operations to the original document will create a new file with a different :new_UUID, the conversion result will be the same.

Document thumbnail

To create a document thumbnail, you should set :target_format/ as jpg or png, and set :number/ of pages as 1.

$
curl -X POST \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    -d '{"paths": [":UUID/document/-/format/jpg/-/page/1/"], "store": "1"}' \
>
    "https://api.uploadcare.com/convert/document/"

Multipage conversion

You can convert a multi-page document into a file group.

The save_in_group parameter determines how the user will receive a multi-page document - an archive or separate files.

An archive

To save converted pages of a multi-page document as an archive, you must pass the save_in_group=0 parameter in the request to set up the conversion task:

$
curl -X POST \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    -d '{"paths": [":UUID/document/-/format/:target-format/"], "store": "1", "save_in_group":"0"}' \
>
    "https://api.uploadcare.com/convert/document/"

You can define possible :target-format for original file.

Note: When converting multi-page documents into image format (:target-format=jpg or :target-format=png), the output will be a zip archive with files, where each document page will be a separate image.

The response will contain the UUID of zip archive:

1
{
2
    "result": [{
3
        "original_source": ":UUID/document/-/format/:target_format/",
4
        "token": ":token",
5
        "uuid": ":zip_UUID"
6
    }],
7
    "problems": {}
8
}

A zip archive with all converted pages can be downloaded via URL with the :zip_UUID:

1
https://ucarecdn.com/:zip_UUID/

Separate files

To form a group of files from converted pages of a multi-page document, you must pass the save_in_group=1 parameter and choose :target-format as image format (jpg or png) in the request to set up the conversion task:

$
curl -X POST \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    -d '{"paths": [":UUID/document/-/format/:target-format/"], "store": "1", "save_in_group":"1"}' \
>
    "https://api.uploadcare.com/convert/document/"

Note: The API response to the conversion request doesn’t indicate the group UUID since the group identifier includes the number of files in the group, which is determined later.

To get the group UUID of the converted files group:

$
curl -X GET \
>
    -H "Content-Type: application/json" \
>
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
    "https://api.uploadcare.com/convert/document/:UUID/"

The response will contain the group UUID:

1
{
2
    "error": null,
3
    "format": {
4
        "name": "pdf",
5
        ...
6
    },
7
    "converted_groups": {
8
        ":target_format": ":group_UUID"
9
    }
10
}

You can view all files in a group by URL:

1
https://ucarecdn.com/:group_UUID/

To further work with group files, use the group REST API.

Conversion groups

If the source document is not multi-page or the conversion of a specific page is requested, for example, :UUID/document/-/format/jpg/-/page/1/, then creating a group is impossible.

All files of converted pages of one multipage document will be added to variations in the same way as if the conversion of each page was requested separately: {"document/-/format/:target_format/-/page/:page_number/": "file_uuid", ...}

Information about the groups formed based on the conversion results to different formats can be obtained from the /convert/document/:UUID/ endpoint. In response to a request to the endpoint, the identifiers of the formed groups will be available along the path .format.converted_groups in the form of a dictionary: {":target_format": ":group_UUID", ...}

If the same file is converted again to the same format, the group ID in the response will be updated, but the previous group and its files will not be deleted.

File formats

Document

Image

Audio

Video

eBook

Archive

CAD

API integrations

You don’t have to code most of the low-level API integrations. We have high-level libraries for all popular platforms:

• JavaScript
• PHP
• Python & Django
• Ruby
• Rails
• Golang
• Rust
• Swift
• Android

Billing

• This feature is available on paid plans.
• This operation uploads a new file.
• Learn how we charge for this operation.