Document conversion

Uploadcare can convert documents from all popular formats via REST API (see our API integrations for most popular programming languages and frameworks).

Converts the input files including the following formats:

  • Microsoft: DOC, DOCX, XLS, XLSX, PPS, PPSX, PPT, PPTX, VSD, VSDX, SKW, WPD, WPS, XLR, PUB, MPP.
  • Apple: KEY, MSG, NUMBERS, PAGES.
  • OpenDocument: ODT, ODS, ODP.
  • Text: TXT, RTF, PDF, DJVU, EML.
  • Data: CSV, XPS, PS, EPS.
  • Image: PSD, AI.

The output file formats (:target-format options): doc, docx, xls, xlsx, odt, ods, txt, rtf, pdf, jpg, png.

Note: When converting multi-page documents to an image format (jpg or png), the output will be a zip archive with one image per page.

How it works

Document conversion works asynchronously through the REST API, unlike the image processing that is 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.

Processing job

The endpoint for your requests is:

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/"bash

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

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 references for POST /convert/document/.

Job status

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/"bash

Check out detailed API references for GET /convert/document/status/{token}/.

Alternatively, you can subscribe to the file.uploaded and file.infected event via the webhooks REST API endpoint.

Job result

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

https://ucarecdn.com/:new_uuid/
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.

Billing

The feature is available on all paid plans. We charge for document conversions separately:

  • Document conversion is billed in units. See the pricing page for details.
  • The total amount of spent conversion units can be found in Usage section in your dashboard.
  • One unit accounts for 50 MB of a file subjected to conversion.
  • Conversion outputs are put to your Uploadcare project. This affects the storage volume that you can also monitor in your dashboard.
  • Upload units are taken according to the size of the resulting file.
  • Your traffic limits are left intact.

API integrations

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