Requests

Every conversion is one HTTPS request:

POST https://api.pdfconversionapi.com/v2/convert/{from}/to/{to}
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data; boundary=...

{from} is the format of your file. {to} is the format you want, or a tool name such as merge, split, compress or protect. The body is a multipart form: the file goes in a field named File, and every option is another field.

Format names

• Format names are case-insensitive: DOCX/to/PDF and docx/to/pdf are the same conversion.
• They may contain letters, digits and hyphens, up to 20 characters. Anything else gets 400 invalid format in the URL.
• A pair we don't convert gets a 404 that names it: conversion from docx to dwg is not supported.
• file/to/pdf, file/to/md and office/to/pdf read the format from the name of the uploaded file instead of the path (Conversions).

Some formats have more than one common name. These are accepted in the URL and mean the same thing:

GET /v2/info lists every pair under its main name only.

Multipart only

The body must be multipart/form-data, which is what curl -F, the files= argument of Python's requests and a FormData body in JavaScript produce. JSON bodies, base64 file data inside JSON, and application/x-www-form-urlencoded bodies are not supported. They get a 400, and that one 400 has a plain-text body instead of our usual JSON error:

Invalid `boundary` for `multipart/form-data` request

The whole request, files and fields together, can be as large as your plan allows, and 100 MB at most on any plan (Limits).

One file: File

Most conversions take exactly one file, in a field named File. Sending two gets 400 this conversion takes exactly one file, and sending none gets 400 no input file was provided.

The file name you send becomes the name of the output, with the new extension: report.docx comes back as report.pdf. We clean the name before using it:

• only the last part of a path is kept;
• characters other than letters, digits, -, _, . and spaces become _;
• leading and trailing dots and spaces are removed, and the name without its extension is cut at 120 characters;
• an upload without a file name is called file, so its output is file.pdf.

An upload named ../../My Photo (1).png, converted to JPG, comes back as My Photo _1_.jpg.

To choose the output name yourself, send the FileName parameter (Responses).

Several files: Files

Four conversions can take more than one file: pdf/to/merge, images/to/pdf, images/to/join and file/to/zip (pdf/to/merge and images/to/join need at least two). Repeat the field Files once per file, or number it Files[0], Files[1] and so on. Files are used in the order they appear in the request body. The number in Files[n] does not reorder them.

File and Files are interchangeable, and field names are case-insensitive, so file, FILES and files[2] all work. Up to 50 files fit in one request.

This merges three PDFs into one and names the result october-billing.pdf. To run it as written, save our sample invoice, terms and timesheet as invoice.pdf, terms.pdf and timesheet.pdf. Each version writes a 107,308-byte october-billing.pdf.

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/pdf/to/merge \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F Files=@invoice.pdf \
  -F Files=@terms.pdf \
  -F Files=@timesheet.pdf \
  -F FileName=october-billing \
  -o response.json

jq -r '.Files[0].FileData' response.json | base64 --decode > october-billing.pdf

# Needs the requests package: pip install requests
import base64
import os

import requests

paths = ["invoice.pdf", "terms.pdf", "timesheet.pdf"]
files = [("Files", open(path, "rb")) for path in paths]
try:
    response = requests.post(
        "https://api.pdfconversionapi.com/v2/convert/pdf/to/merge",
        headers={"Authorization": f"Bearer {os.environ['PDFCONVERSIONAPI_KEY']}"},
        files=files,
        data={"FileName": "october-billing"},
        timeout=240,
    )
finally:
    for _, f in files:
        f.close()
result = response.json()
if not response.ok:
    raise SystemExit(f"{result['Code']}: {result['Message']}")

merged = result["Files"][0]
with open(merged["FileName"], "wb") as out:
    out.write(base64.b64decode(merged["FileData"]))
print(merged["FileName"], merged["FileSize"], "bytes")

// Needs Node.js 20 or later. Save it as merge.mjs and run: node merge.mjs
import { readFile, writeFile } from "node:fs/promises";

const form = new FormData();
for (const path of ["invoice.pdf", "terms.pdf", "timesheet.pdf"]) {
  form.append("Files", new Blob([await readFile(path)]), path);
}
form.append("FileName", "october-billing");

const response = await fetch("https://api.pdfconversionapi.com/v2/convert/pdf/to/merge", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PDFCONVERSIONAPI_KEY}` },
  body: form,
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.Code}: ${result.Message}`);

const merged = result.Files[0];
await writeFile(merged.FileName, Buffer.from(merged.FileData, "base64"));
console.log(merged.FileName, merged.FileSize, "bytes");

Named file fields

A few tools take a second file with its own role. It goes in a field named after that role:

Any field that carries a file name and isn't File or Files is read as a named file. Named files count toward both the 50-file limit and the 100-parameter limit.

This stamps logo.png on every page of invoice.pdf at 30% opacity:

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/pdf/to/image-watermark \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@invoice.pdf \
  -F ImageFile=@logo.png \
  -F Opacity=30 \
  -o response.json

jq -r '.Files[0].FileData' response.json | base64 --decode > invoice-stamped.pdf

Parameters

Every field that is not a file is a parameter, sent as text: -F PageRange=1-3 in curl, data={"PageRange": "1-3"} in Python, form.append("PageRange", "1-3") in JavaScript.

• Names use letters, digits and _, up to 64 characters. Any other name gets 400 parameter names must be letters, digits or _.
• Names are case-insensitive. PageRange, pagerange and PAGERANGE are the same parameter. If you send one twice, the last value wins.
• Values can be up to 64 KiB (65,536 bytes). A longer one gets 400 parameter FileName is too long, naming the parameter.
• At most 100 parameters per request. The 101st gets 400 too many parameters.
• An empty value counts as not sent.
• Yes/no values accept true or false, 1 or 0, yes or no, on or off, in any case.
• Numbers are checked against a range. ImageResolution=700 gets 400 ImageResolution must be between 36 and 600.
• Only form fields are read. Parameters in the URL's query string, such as ?PageRange=1-3, are ignored.

This renders pages 1 and 2 of a PDF as JPG images at 72 DPI. The output below is from our sample PDF, saved as season-guide.pdf:

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/pdf/to/jpg \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@season-guide.pdf \
  -F PageRange=1-2 \
  -F ImageResolution=72 \
  -o response.json

jq -c '.Files[] | {FileName, FileSize}' response.json

{"FileName":"season-guide-1.jpg","FileSize":65272}
{"FileName":"season-guide-2.jpg","FileSize":66627}

Two parameters work across conversions:

The parameters each conversion reads are listed on its page, for example DOCX to PDF or PDF to JPG.

Page ranges: PageRange

Conversions that work page by page, such as PDF to JPG, pdf/to/extract, pdf/to/split and HTML to PDF, choose pages with PageRange. Pages count from 1. Without PageRange, most of them use every page; pdf/to/extract and pdf/to/delete-pages need one. These are the forms it accepts, with the pages each one gave on our six-page sample statement:

• last means the last page, and upper or lower case both work. Spaces around the numbers are ignored.
• Pages come back in document order, each one once: 4,2 gives pages 2 and 4, and 3,1,3 gives 1 and 3.
• The end of a range can be past the last page, as in 4-10 above. A page on its own, or the first page of a range, can't: on the six-page sample, 7 and 2,7 get 400 PageRange asks for page 7, but the document has 6 pages, and no file comes back.
• Anything else, such as 0, 3-1 or last-2, gets 400 PageRange '3-1' is not valid (example: 1-3,5), with your range in the quotes.

Not every conversion can apply PageRange. One that can't refuses any value other than ConvertAPI's default, with 400 PageRange is not supported yet for DOCX → PDF (next section).

Options we don't support yet

Our parameter names follow ConvertAPI's documentation for each conversion, and so do most defaults (three differ). When you set one of those documented options to a value other than ConvertAPI's default and our converter can't apply it, the request fails with a 400 that names the option, instead of returning a file made without it:

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/pdf/to/jpg \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@season-guide.pdf \
  -F BitDepth=8

{"Code":400,"Message":"BitDepth is not supported yet for PDF → JPG"}

Sending the option at its default value (BitDepth=default) is accepted. A parameter that is not an option of this conversion at all is ignored, so if a setting seems to have no effect, check the spelling of its name.

URLs are not fetched

File must contain the file's bytes. We never download anything for you:

• A File field that holds a URL as text is read as the file. Most conversions then answer 422 with a message that starts the input file could not be read, but a text input such as HTML is converted as it is, so you get a PDF of the URL text.
• HTML conversions don't support the Url parameter. With a file attached, it gets 400 Url is not supported yet; send the page as an HTML file in File.

Download the file or page on your side and upload it. Migrating from another conversion API lists the other request styles we don't accept.

We ran every example on this page on 2026-11-04 against the API server running locally in a container, built the same way as the hosted service, with only the base URL changed (curl 8.7.1, jq 1.8.1, Python 3.14.2 with requests 2.34.2, Node.js 24.15.0).