Document conversion
On this page
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.
- Start a processing job via REST API. Send an input file UUID with necessary processing operations.
- Wait until the processing job status becomes
finished
. - 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 eitherjpg
orpng
. 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: