Docs

Convert image files

Convert image files to PNG, JPEG, WebP, TIFF, or PDF.

POST /v1/images/convert. Authenticated with your RelayPDF API key. Choose binary output, a temporary download URL, or an asynchronous job.

Request example

Replace the example input URL with a publicly accessible file you control. The example authorizes up to $1; successful work is charged for measured usage. Use a new idempotency key for a different request.

curl

curl https://api.relaypdf.com/v1/images/convert \
  -H "Authorization: Bearer $RELAYPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-convert-example-001" \
  -H "X-RelayPDF-Max-Charge-Microdollars: 1000000" \
  --data '{"url":"https://example.com/image.png","response":"url","filename":"converted.webp","options":{"format":"webp","width":1200,"quality":85}}'

Input and response

Provide exactly one of url, file, or fileId. All other fields are optional unless an operation option is marked required.

Field	Meaning
url	HTTPS input URL; public URL input is limited to 15 MiB.
file	Base64 input, optionally a data URI; decoded limit 15 MiB.
fileId	Private upload ID from POST /v1/files; maximum 100 MiB.
response	binary (default), url, or async.
filename	Optional output filename matching the actual output extension.
callbackUrl	Optional HTTPS per-job callback; unsigned.
options	Only use the options documented for the selected operation.

Operation options

Pass these fields inside the options object. Unknown or irrelevant options should not be relied upon.

Option	Default	Meaning
format	png	png, jpeg, webp, tiff, or pdf.
width / height	Original	Maximum bounding dimensions in pixels; preserves aspect ratio and does not upscale.
quality	85	Integer from 1 to 100; effect depends on output format.

Output and limitations

TIFF and PDF output can preserve up to 100 input frames; other output formats use the first frame. JPEG/PDF use a white background for transparency. Image pixel and output-size limits apply. This converts an image file; /v1/images renders HTML or URLs.

PDF inputs are limited to 500 pages and returned output to 32 MiB. Uploaded inputs expire after 24 hours. Download successful output before its 24-hour URL expires.

Failed jobs are unbilled. A 402 can mean insufficient available credit or a spending limit; a 409 indicates an idempotency conflict; a 413 indicates an exceeded size limit. Do not retry invalid inputs unchanged.

Node SDK

Use a release version containing client.process. With older published packages, call REST until the matching SDK version is available.

TypeScript

import { RelayPDF } from "@relaypdf/sdk";
const client = new RelayPDF({ apiKey: process.env.RELAYPDF_API_KEY! });
const result = await client.process("image-convert", {
  "url": "https://example.com/image.png",
  "response": "url",
  "filename": "converted.webp",
  "options": {
    "format": "webp",
    "width": 1200,
    "quality": 85
  }
}, { idempotencyKey: "image-convert-example-002", maxChargeMicrodollars: 1_000_000 });
console.log(result);

Pricing and job lifecycle

The assigned native rate applies. Final release pricing is $0.0004 per successful job plus $0.0005 per native execution second. Existing accounts retain their assigned rate. Reservations reduce available credit before work; unused funds return after settlement. See /docs/billing and /docs/idempotency for receipts, limits, and retries.

Docs hub →Node.js SDK →Playground →