Document Conversions

Uploadcare allows converting documents to the following target formats: DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, PNG.

Document Conversion works via our REST API. The general conversions workflow is described here. Putting it simply, you post a conversion job and get a result once the operation is complete. If the conversion operation completes successfully, you can address the outputs via respective CDN URLs: their aliases.

Enabling Document Conversion

Document Conversion works on a per-project basis and is currently available on demand. To enable the feature:

  • Discover the public API key of a project you want to use as a Document Conversion environment.
  • Drop us a line at hello@uploadcare.com providing your request together with the public API key.

Document Conversion billing

We charge for document conversions separately:

  • Document Conversion is billed in units.
  • The total amount of spent conversion units can be found in your dashboard.
  • The single conversion unit costs 0.045 USD.
  • One unit accounts for 50 MB of a file subjected to conversion.
  • Conversion outputs are put to your Uploadcare project; this affects your storage limits that you can also monitor in your dashboard.
  • Each conversion operation takes one upload unit. Document conversions are applied externally, so we upload an output to your account once it is generated.
  • Your traffic limits are left intact.

Document Conversion workflow

Document Conversion works via REST API, and the endpoint for the requests is:

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

The general Document Conversion workflow is as follows:

  1. You post a conversion job by making a REST API request; the conversion params are passed in a request together with a source file UUID. Do not forget to properly authorize your request.
  2. You wait until the conversion job status becomes finished.
  3. The converted target file can now be addressed via its UUID passed in a response; the UUID can be used for any further REST API routines. Another way to address the output is via a CDN URL alias you provided in conversion a request.

CDN URL aliases are interchangeable with respective processed file UUIDs. Check out this live example or learn more about proper URL formatting for conversion jobs.

With Document Conversion, operations are not applied on the fly. You must first post a conversion job providing a proper request parameter holding your input file identifier and a target format.

Note, Document Conversion does not alter your inputs: it creates processed outputs as separate files.

A good example of working with converted file UUIDs would be subscribing to the file.uploaded event via the webhooks REST API endpoint. This allows you to know when conversion routines are complete without checking your conversion job status. Learn more about webhooks here.

Posting a file conversion job

POST /convert/document/

The requests you make should be in line with our general REST API workflow. The two following params should be passed in a request:

  • paths, an array of UUIDs of your source documents to convert together with the specified target format.
  • store, a flag indicating if Uploadcare should store your outputs.

When store is set to "0", your converted outputs will only be available for 24 hours. "1" indicates converted files should be made permanently available. If the parameter is omitted, we use the Auto file storing setting related to an Uploadcare project identified by the public_key provided in the auth-param.

Input file identifier formatting

Your source file identifiers should be formatted as follows,

/:uuid/document/

The output format should be specified after the /-/ delimiter:

/:uuid/document/-/format/:target-format/

You can also provide a complete CDN URL. It can then be used as an alias to your converted file UUID:

https://ucarecdn.com/:uuid/document/-/format/:target-format/

Summing up the params:

  • :uuid identifies the source file you want to convert; :uuid should be followed by /document/; otherwise your request will return an error.
  • /-/ is a necessary delimiter that helps our API tell file identifiers from processing operations.
  • /format/ is the name of Uploadcare file conversion operation.
  • :target-format defines the target format you want a source file converted to. The supported values for :target-format are: doc, docx, xls, xlsx, odt, ods, rtf, txt, pdf (default), jpg, png.

In case no :target-format is specified, its value defaults to pdf.

Requesting to convert a single file

Make sure to use your project keys instead of your_public_key, your_secret_key; the keys should point to an Uploadcare project with enabled Document Conversion feature. The :uuid of the source file to convert should sit in the project specified by your_public_key. The :target-format should be set according to one of the supported formats, see this section for details.

Request,

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+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/"

Response,

{
  "problems": {},
  "result": [
    {
      "original_source": ":uuid/document/-/format/:target-format/",
      "token": 3724130,
      "uuid": ":uuid-converted"
    }
  ]
}

Technically, once you convert a file you get two UUIDs: the first is included in original_source, and the second sits in uuid. That’s because of the two existing methods to address converted files.

While https://ucarecdn.com/:uuid/document/-/format/:target-format/ will work as a CDN URL alias for a converted file, the actual file identifier to use with other REST API routines would be :uuid-converted.

Conversion job output

In a response you get a JSON holding the following parameters:

  • problems, problems related to your conversion job, if any.
  • result, info related to your converted output(-s):
    • original_source, source file identifier including a target format, if present.
    • token, a conversion job token that can be used to get a job status.
    • uuid, a UUID of your converted document.

When posting a multi-file conversion job, you get separate results and status tokens for each source.

Converting multiple documents

Request,

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple your_public_key:your_secret_key" \
     -d '{"paths": [
          ":uuid/document/",
          ":uuid/document/-/format/jpg/",
          ":uuid"], "store": "1"}'
\
     "https://api.uploadcare.com/convert/document/"

Response,

{
  "problems": {
    ":uuid": "Bad path \":uuid\". Use :uuid/document/",
  },
  "result": [
    {
      "original_source": ":uuid/document/-/format/jpg/",
      "token": 445630631,
      "uuid": ":uuid-processed"
    },
    {
      "original_source": ":uuid/document/",
      "token": 445630637,
      "uuid": ":uuid-processed"
    }
  ]
}

As you can see, there is a problem with one of the inputs in the above example. The problem is caused by the incorrect entry in paths: no /document/ is included in the third item.

Possible errors

Here are the errors specific to Document Conversion; you can also get errors related to our REST API.

In case you do not provide any input in the request,

[HTTP 400] \"paths\" parameter is required.

In case the Document Conversion feature is disabled for a project, see more on enabling the feature here.

[HTTP 400] Document Conversion feature is not available for this project.

Checking conversion job status

GET /convert/document/status/:token/

Once you get a conversion job result, you can acquire a conversion job status via token. Just put it in your request URL as :token.

Get job status, example

Request,

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple your_public_key:your_secret_key" \
     "https://api.uploadcare.com/convert/document/status/:token/"

Response,

{
  "status": "processing",
  "error": null,
  "result": {
    "uuid": ":uuid-processed"
  }
}

Conversion job status output

A conversion job output is a JSON holding the following parameters:

  • status, conversion job status, can have one of the following values:
    • pending — a source file is being prepared for conversion.
    • processing — conversion is in progress.
    • finished — the conversion is finished.
    • failed — we failed to convert the source, see error for details.
    • canceled — the conversion was canceled.
  • error, holds a conversion error if we were unable to handle your file.
  • result, repeats the contents of your conversion output.
  • uuid, a UUID of a converted target file.

Once your conversion job is finished, you are free to add any RFC3986 compliant filenames when accessing your outputs via their CDN URL aliases, here is an example:

https://ucarecdn.com/:uuid/document/-/format/pdf/report-converted.pdf

Possible status-check errors

In case you did not enable the Document Conversion feature,

[HTTP 400] Document Conversion feature is not available for this project.

In case you provided an invalid conversion job token,

[HTTP 404] Job with specified ID was not found.

In case your requests are throttled due to their high rate,

[HTTP 429] Requests rate limit hit.

The error is provided with the value for the Retry-After header and an info string like Request was throttled. Expected available in 10.0 seconds.

In case we experience an internal error with the service,

[HTTP 500] Document Conversion service error.

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.