Endpoint reference

POST /api/image-to-pdf

Turn one or more JPG or PNG images into a single PDF, one image per page, in the order you send them. Pages match the image size or a standard A4 or Letter page. Returns application/pdf.

Request

Method: POST. URL: https://pdfops.dev/api/image-to-pdf. Body: multipart/form-data.

FieldTypeRequiredDescription
pdf (repeated)File (JPG or PNG)Yes, 1 to 100An image file, up to 4 MB each; all files together must stay under 4.5 MB, Vercel's platform request limit. Repeat the field name pdf for each image, the same field name /api/merge uses. Pages follow the order of the fields. image is accepted as an alias when the request has no pdf field.
page_sizeStringNofit (default), a4 or letter. See Pages.
orientationStringNoauto (default), portrait or landscape. Used for a4 and letter; ignored for fit. auto picks landscape for an image wider than it is tall, per image.
marginNumberNoPoints (72 to the inch), 0 to 200. Default 0 for fit, 36 for a4 and letter.

The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 1 request, however many images it holds. Check consumption with GET /api/usage.

Which files count as images

The type comes from the first bytes of each file, never from the file name or the Content-Type of the part. A file that starts with JPEG or PNG signature bytes is an image; anything else, including a PDF, returns unsupported_image_format. /api/merge reads its inputs the same way, with one exception that keeps old merges working: a file that starts with JPEG or PNG bytes but also contains a %PDF- header and loads as a PDF (a PDF with junk in front) is merged as a PDF.

Pages

page_sizePageImage placement
fitThe size of the image with 1 pixel = 1 point, plus margin on every side. If the long side would pass 5,000 points, the page is scaled down to 5,000. A page whose short side would be under 3 points is made 3 points (a 2 × 2 pixel image gives a 3 × 3 point page).Fills the page inside the margin.
a4595.28 × 841.89 points, portrait or landscape by orientation.Centred, scaled down to fit inside the margin with its aspect ratio kept, never enlarged.
letter612 × 792 points, portrait or landscape by orientation.Same as a4.

A sliver such as 1 × 5,000 pixels cannot make a valid fit page and returns image_aspect_ratio; use a4 or letter, add a margin, or crop it. A margin of 200 points leaves a positive drawing area on A4 and Letter, so there is no margin that fails for being too large, and a margin over 200 returns invalid_parameter.

Limits

LimitValueError code
Images per request100too_many_images
Size of one file4 MBpdf_too_large
Whole request4.5 MBrequest_too_large (413)
PNG size10 million pixels, and a memory estimate of 320 MiB for one PNG (8-bit RGB or RGBA fits up to the pixel limit; 16-bit RGBA fits up to about 5.8 million pixels)image_too_large
PNG memory across the requestThe memory estimates of all PNGs in one request add up to at most 300 MiB. JPEGs are not counted. See What fits in one request.images_too_large_together
JPEG size250 million pixels (read from the file header, before anything is embedded)image_too_large
Fit page, long side5,000 points; larger images are scaled down, not refusedNone
Fit page, short sideAt least 3 points; tiny images are enlarged, slivers are refusedimage_aspect_ratio
Margin0 to 200 pointsinvalid_parameter

JPEG files are embedded as they are, so the cost of a JPEG is its file size, not its pixel count: on our servers' runtime, embedding 12, 48, 100 and 200 megapixel JPEGs took 1 to 3 MiB of extra memory and about 10 ms each. The JPEG limit exists to refuse files that claim an absurd size (a header can claim 65,535 × 65,535 pixels), not to save memory. It covers 200 megapixel phone sensors. The 4 MB file limit still applies to every file, so a very large photo may need to be saved at a lower quality.

What fits in one request

Every PNG is checked and rebuilt before use, which costs memory, so PNGs in one request share a memory budget. The estimate depends on the pixel count and the colour type, so it is not a count of images. Approximate numbers for 8-bit PNGs in one request:

PNG sizeRGB (no alpha)RGBA (with alpha)
1920 × 108064
2560 × 144032
3840 × 2160 (4K)11

A 16-bit PNG costs more: one 4K 16-bit RGB PNG does not fit at all. JPEGs are not subject to this budget, so a request of any number of JPEGs up to the other limits works. When a request is too big, send the images in several requests (one 4K PNG each) and join the resulting PDFs with /api/merge, which takes PDFs and images. A PNG saved as a JPEG also avoids the limit.

Response

On success: 200 OK, Content-Type: application/pdf, body is the PDF binary, one page per image.

On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }. For a problem with one image, details starts with pdf[N]:, where N is the 0-based position of the file in the request.

Error codes

Error codeStatusTrigger
invalid_multipart400Request body could not be parsed as multipart/form-data.
missing_images400The request has no pdf (or image) file field.
too_many_images400More than 100 image files in the request. Chain calls for more.
pdf_too_large400One file is over 4 MB. The name is shared with the PDF endpoints.
unsupported_image_format400A file does not start with JPEG or PNG signature bytes. details names the index and says: Supported formats: JPG, PNG.
invalid_image400The image is corrupt or truncated, is an animated PNG, has a malformed or unsupported JPEG header (lossless, arithmetic, 12-bit) or no end-of-image marker, or has image data that cannot be decoded.
image_too_large400One image is over the pixel or memory limit in Limits.
images_too_large_together400The PNGs in the request are too large to process together. See What fits in one request: split the request, then join the PDFs with /api/merge.
image_aspect_ratio400A fit page for this image would have a short side under 3 points even after enlarging it.
invalid_parameter400page_size, orientation or margin is not one of the allowed values.
internal_error500The PNG check could not run in this environment. Retryable.
save_failed500PDF serialization failed. Retryable.
request_too_large413The whole request body is over 4.5 MB (Vercel's platform request limit). Rejected before anything is parsed.
invalid_api_key401An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing.
rate_limited429The anonymous per-IP limit (100/month) or your key's monthly quota is used up. Retry-After gives seconds until next calendar month.

Example

Three photos into one PDF, each page the size of its image:

curl -X POST https://pdfops.dev/api/image-to-pdf \
  -F "pdf=@page1.jpg" \
  -F "pdf=@page2.jpg" \
  -F "pdf=@scan.png" \
  -o photos.pdf

The same images on A4 pages with a 36 point margin, landscape or portrait chosen per image:

curl -X POST https://pdfops.dev/api/image-to-pdf \
  -F "pdf=@page1.jpg" \
  -F "pdf=@page2.jpg" \
  -F "page_size=a4" \
  -o photos-a4.pdf

Keyless calls work: 100 requests per IP per month with no key. With a key, add -H "X-API-Key: pdfops_live_..." to any request here; it raises your quota to your tier's.

Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.

Get a free API key

Code examples

Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.

JavaScript (Node.js 22+) — built-in fetch + FormData
import { readFile, writeFile } from 'node:fs/promises';

const fd = new FormData();
for (const name of ['page1.jpg', 'page2.jpg', 'scan.png']) {
  fd.append('pdf', new Blob([await readFile(name)]), name);
}
fd.append('page_size', 'a4');

// The key is optional: send the header only when you have one.
const headers = process.env.PDFOPS_API_KEY ? { 'X-API-Key': process.env.PDFOPS_API_KEY } : {};
const res = await fetch('https://pdfops.dev/api/image-to-pdf', { method: 'POST', headers, body: fd });
if (!res.ok) {
  const err = await res.json();
  throw new Error(`PDFops image-to-pdf failed: ${err.error}: ${err.details}`);
}
await writeFile('photos.pdf', Buffer.from(await res.arrayBuffer()));
Python — requests
import os, requests

# The key is optional: send the header only when you have one.
headers = {"X-API-Key": os.environ["PDFOPS_API_KEY"]} if os.environ.get("PDFOPS_API_KEY") else {}
names = ["page1.jpg", "page2.jpg", "scan.png"]
files = [("pdf", (n, open(n, "rb"))) for n in names]
res = requests.post(
    "https://pdfops.dev/api/image-to-pdf",
    headers=headers,
    files=files,
    data={"page_size": "a4"},
)
res.raise_for_status()
open("photos.pdf", "wb").write(res.content)

From an AI agent (MCP)

The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_image_to_pdf tool, with image_paths (an array of https:// URLs or data:image/jpeg;base64,... and data:image/png;base64,... URIs), and optional page_size, orientation and margin. It returns the PDF inline as an application/pdf resource. See the MCP page.

Behavioral notes

FAQ

How do I convert a JPG to a PDF with an API?

Send the image as a pdf file field in a multipart/form-data POST to /api/image-to-pdf. The response is a PDF with one page that is the size of the image. Repeat the field to put several images in one PDF, one per page.

Can I mix images and PDFs in one file?

Yes, with /api/merge. It accepts JPG and PNG files among its inputs and turns each image into one page, the same as page_size=fit here. This endpoint takes images only, and a PDF sent to it returns unsupported_image_format.

Why did my phone photo come out rotated or sideways?

It should not: a JPEG's EXIF orientation (values 1 to 8) is applied, so the page shows the photo the way a viewer would. If a photo looks wrong, the file probably has no orientation tag, or the tag is wrong. PNG files carry no orientation that is read.

Why was my image rejected with image_too_large?

A PNG is limited to 10 million pixels and to a memory estimate that depends on its colour type and bit depth, so a 16-bit RGBA PNG is refused at fewer pixels than an 8-bit one. A JPEG is limited to 250 million pixels. Downscale the image, save the PNG as 8-bit, or send a JPEG.

Does it accept HEIC, WebP, GIF or TIFF?

No. Only JPG and PNG are read, and the type is taken from the first bytes of the file, never from the file name or the content type. Anything else returns unsupported_image_format. Convert the image to JPG or PNG first.

Related: Merge PDFs (images accepted) · Text to PDF · Stamp text and images.

Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email and the key arrives in your inbox.

Get a free API key