Improve performance with a custom file conversion workflow

One of the core features of our conversion service is the conversion workflow. We have seen many integrations implement multi-step file processing in slow, hard-to-reuse ways, so we decided to describe the pattern in detail.

We solved this problem with what we call REST API conversion workflows. It simply means applying multiple conversions to a file that is already stored on our server. You can process the file over and over again by calling the appropriate conversion endpoints via the REST API. There is no need to download an intermediate result and re-upload it. The diagram below describes the process of the real-world example we will discuss in a moment.

Why use conversion workflows?

Conversion workflows not only improve performance but also give you the flexibility to manage your file conversions step by step. This way, you gain the ability to handle any exceptions that might occur along the way. This REST API pattern also lets you resume the workflow from the step that failed, without rerunning the whole process. Now let's dive into a real-world demo!

How chaining works

Every conversion endpoint accepts the StoreFile parameter. When you set StoreFile=true, the converted files are kept on our server for a limited time, and the JSON response returns a Url and a FileId for each result instead of the file content. You then pass that URL (or file id) as the input of the next conversion, so intermediate files never travel back to your machine.

The examples below use plain cURL calls, so you can see exactly what happens on the wire. The same chaining works in every language, either with raw HTTP requests or with one of our SDKs.

One tip before we start: check whether a single endpoint already covers your combination. For example, the Images to PDF API turns a whole set of images into one PDF document in a single call. Chaining is for the jobs that no dedicated converter covers end to end.

Real-world example

For our demo, let's take a common task: turning a multi-page PDF into images. Converting a PDF to JPG produces one image per page, so a 30-page document returns 30 files. Downloading them one by one is exactly the kind of overhead workflows remove. Instead, we will store the page images on the server and pack them into a single ZIP archive with a second call.

First, convert the PDF to JPG and store the results:

curl -X POST "https://v2.convertapi.com/convert/pdf/to/jpg" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "File=@report.pdf" \
  -F "StoreFile=true"

The response contains the URL and id of every stored page image:

{
  "ConversionCost": 3,
  "Files": [
    {
      "FileName": "report.jpg",
      "FileSize": 526012,
      "FileId": "d57646acef91155eb7a57376e9cf8d55",
      "Url": "https://v2.convertapi.com/d/d57646acef91155eb7a57376e9cf8d55/report.jpg"
    },
    {
      "FileName": "report-2.jpg",
      "FileSize": 500216,
      "FileId": "dfaca13bc861c529d00d22cfacf71c63",
      "Url": "https://v2.convertapi.com/d/dfaca13bc861c529d00d22cfacf71c63/report-2.jpg"
    },
    {
      "FileName": "report-3.jpg",
      "FileSize": 516911,
      "FileId": "4c78541c67d66045dfe5378dc8852ae5",
      "Url": "https://v2.convertapi.com/d/4c78541c67d66045dfe5378dc8852ae5/report-3.jpg"
    }
  ]
}

Now pass the stored file URLs to the ZIP endpoint. Since this is the last step of the workflow, we no longer need StoreFile. Instead, we request the raw file bytes with the Accept: application/octet-stream header and let cURL save the archive directly:

curl -X POST "https://v2.convertapi.com/convert/any/to/zip" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/octet-stream" \
  -F "Files[0]=https://v2.convertapi.com/d/d57646acef91155eb7a57376e9cf8d55/report.jpg" \
  -F "Files[1]=https://v2.convertapi.com/d/dfaca13bc861c529d00d22cfacf71c63/report-2.jpg" \
  -F "Files[2]=https://v2.convertapi.com/d/4c78541c67d66045dfe5378dc8852ae5/report-3.jpg" \
  -o report-pages.zip

That's it - one PDF went in, and a single ZIP archive with every page as an image came out. The page images themselves never traveled back to your machine between the steps.

Adding more steps

Another common example is to convert multiple DOCX documents into PDFs, merge them into a single PDF, and finally protect the merged result with a password.

Convert each document to PDF and store the result:

curl -X POST "https://v2.convertapi.com/convert/docx/to/pdf" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "File=@documents/document1.docx" \
  -F "StoreFile=true"

Merge the stored PDFs, again keeping the result on the server for the next step:

curl -X POST "https://v2.convertapi.com/convert/pdf/to/merge" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "Files[0]=https://v2.convertapi.com/d/d57646acef91155eb7a57376e9cf8d55/document1.pdf" \
  -F "Files[1]=https://v2.convertapi.com/d/dfaca13bc861c529d00d22cfacf71c63/document2.pdf" \
  -F "StoreFile=true"

Finally, protect the merged PDF with a password and download it:

curl -X POST "https://v2.convertapi.com/convert/pdf/to/protect" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/octet-stream" \
  -F "File=https://v2.convertapi.com/d/2f742a059ab5ae601f41f4503bb2a7f5/merged.pdf" \
  -F "UserPassword=testpassword" \
  -o protected.pdf

The full REST API workflow reference can be found in our documentation.

Conclusion

To put it in a nutshell, conversion chaining is the best practice for processing documents in multiple steps, with both performance and flexibility perks. It works with plain REST calls, as shown above, and with all of our SDKs. Use this approach to write clean, reusable, and performance-oriented code!

Read more about conversion workflows in our documentation.

Happy coding!