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.
| Field | Type | Required | Description |
|---|---|---|---|
pdf (repeated) | File (JPG or PNG) | Yes, 1 to 100 | An 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_size | String | No | fit (default), a4 or letter. See Pages. |
orientation | String | No | auto (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. |
margin | Number | No | Points (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.
- JPEG: baseline and progressive, grey, RGB and CMYK. CMYK support is for Adobe-style CMYK JPEGs, the kind Photoshop and cameras write; other CMYK files may show inverted colours. Lossless, arithmetic-coded, hierarchical and 12-bit JPEGs return
invalid_image. So does a JPEG with more than 1,000 segments in front of the image, a second frame header, or no image data (real files have a few dozen segments at most). A JPEG is embedded as it is, without re-encoding, so the image quality is unchanged. The file must reach its end-of-image marker (a file that was cut short is refused withinvalid_image); bytes after that marker, such as the video in an Android motion photo or a second picture, are allowed and ignored. EXIF orientation 2 to 8 is applied (read from the first Exif block, as a SHORT or LONG value) by flipping or rotating the image on the page; for orientations 5 to 8 the page width and height are swapped. - PNG: grey, RGB, palette, grey with alpha and RGBA, at any bit depth PNG allows, interlaced or not. Transparency is kept. Animated PNGs return
invalid_image. The file is checked and rebuilt before it is used, so extra chunks (text, colour profile) are dropped and bytes after the end of the PNG are ignored. PNG orientation data is not read.
Pages
page_size | Page | Image placement |
|---|---|---|
fit | The 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. |
a4 | 595.28 × 841.89 points, portrait or landscape by orientation. | Centred, scaled down to fit inside the margin with its aspect ratio kept, never enlarged. |
letter | 612 × 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
| Limit | Value | Error code |
|---|---|---|
| Images per request | 100 | too_many_images |
| Size of one file | 4 MB | pdf_too_large |
| Whole request | 4.5 MB | request_too_large (413) |
| PNG size | 10 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 request | The 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 size | 250 million pixels (read from the file header, before anything is embedded) | image_too_large |
| Fit page, long side | 5,000 points; larger images are scaled down, not refused | None |
| Fit page, short side | At least 3 points; tiny images are enlarged, slivers are refused | image_aspect_ratio |
| Margin | 0 to 200 points | invalid_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 size | RGB (no alpha) | RGBA (with alpha) |
|---|---|---|
| 1920 × 1080 | 6 | 4 |
| 2560 × 1440 | 3 | 2 |
| 3840 × 2160 (4K) | 1 | 1 |
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 code | Status | Trigger |
|---|---|---|
invalid_multipart | 400 | Request body could not be parsed as multipart/form-data. |
missing_images | 400 | The request has no pdf (or image) file field. |
too_many_images | 400 | More than 100 image files in the request. Chain calls for more. |
pdf_too_large | 400 | One file is over 4 MB. The name is shared with the PDF endpoints. |
unsupported_image_format | 400 | A file does not start with JPEG or PNG signature bytes. details names the index and says: Supported formats: JPG, PNG. |
invalid_image | 400 | The 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_large | 400 | One image is over the pixel or memory limit in Limits. |
images_too_large_together | 400 | The 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_ratio | 400 | A fit page for this image would have a short side under 3 points even after enlarging it. |
invalid_parameter | 400 | page_size, orientation or margin is not one of the allowed values. |
internal_error | 500 | The PNG check could not run in this environment. Retryable. |
save_failed | 500 | PDF serialization failed. Retryable. |
request_too_large | 413 | The whole request body is over 4.5 MB (Vercel's platform request limit). Rejected before anything is parsed. |
invalid_api_key | 401 | An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing. |
rate_limited | 429 | The 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.
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
- One image, one page. There is no multi-page image support (animated PNG, multi-frame TIFF).
- The output is deterministic. The same images and options give the same bytes: the creation date, modification date and producer are pinned.
- Images are not resampled. A JPEG is stored as it was sent. A PNG is stored losslessly, and the PDF can be much larger than the PNG file: PNG compression of repeating patterns does not carry over, and a PNG with an alpha channel is stored as separate colour and alpha data. A 4000 × 2500 RGBA PNG of 0.3 MB produced a 29 MB PDF in our test, the same size
/api/editproduces for that image. Plan for up to about 4 bytes per pixel for RGBA and 3 for RGB in the worst case. - No OCR. The pages are pictures; the text in a scanned image is not searchable.
- Checks run before any work. Every image is checked from its header first, so a request that is going to be refused for size or type is refused without decoding anything.
- Limits: 100 images, 4 MB per file, 4.5 MB per request (Vercel's platform limit).
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.