API Documentation

Image Conversion API#

A single REST API converts images between JPEG, PNG, WebP, HEIC, and SVG, renders PDF pages as JPEGs, and compresses images in place. Every endpoint accepts a multipart/form-data upload and converts synchronously using Pillow, CairoSVG, pillow-heif, or PyMuPDF depending on the format pair. By default the response is the raw converted file; set direct_download=false to receive JSON metadata with a presigned download URL instead.

Supported conversions#

Conversion Endpoint Description
JPEG to PNG POST /v1/convert/jpeg-to-png Converts a .jpeg/.jpg upload to a lossless PNG with full color fidelity.
PNG to JPEG POST /v1/convert/png-to-jpeg Converts a .png to a maximum-quality JPEG, compositing transparent areas onto a white background.
JPEG to SVG POST /v1/convert/jpeg-to-svg Base64-embeds the JPEG as a data URI inside an SVG <image> element. This is a raster wrapper, not vectorization.
SVG to JPEG POST /v1/convert/svg-to-jpeg Rasterizes the SVG with CairoSVG and returns a JPEG, compositing transparency onto a white background.
JPEG to HEIC POST /v1/convert/jpeg-to-heic Encodes a .jpeg/.jpg upload as a high-quality HEIC file using the HEIF codec.
HEIC to JPEG POST /v1/convert/heic-to-jpeg Decodes a .heic or .heif upload (e.g. iPhone photos) and produces a high-quality JPEG.
JPEG to WebP POST /v1/convert/jpeg-to-webp Produces a high-quality WebP with a smaller file size than the equivalent JPEG for web delivery.
WebP to JPEG POST /v1/convert/webp-to-jpeg Converts a .webp to JPEG, compositing any transparent areas onto a white background.
PNG to SVG POST /v1/convert/png-to-svg Embeds the PNG as a base64 data URI in an SVG wrapper matching the image's pixel dimensions. This is not vectorization.
SVG to PNG POST /v1/convert/svg-to-png Rasterizes the SVG with CairoSVG at its declared size, preserving transparency in the PNG output.
PNG to HEIC POST /v1/convert/png-to-heic Converts a .png to HEIC, compositing transparent areas onto a white background.
HEIC to PNG POST /v1/convert/heic-to-png Converts a .heic or .heif upload to a lossless PNG with full color fidelity.
PNG to WebP POST /v1/convert/png-to-webp Converts a .png to WebP with the alpha channel (transparency) preserved.
WebP to PNG POST /v1/convert/webp-to-png Converts a .webp to a lossless PNG with transparency preserved.
SVG to HEIC POST /v1/convert/svg-to-heic Renders the SVG with CairoSVG and encodes it as HEIC at maximum quality on a white background.
HEIC to SVG POST /v1/convert/heic-to-svg Decodes the HEIC to PNG and embeds it as a base64 data URI in an SVG wrapper. This is not vectorization.
SVG to WebP POST /v1/convert/svg-to-webp Renders the SVG with CairoSVG and encodes it as WebP at maximum quality with transparency preserved.
WebP to SVG POST /v1/convert/webp-to-svg Decodes the WebP to PNG and embeds it as a base64 data URI in an SVG wrapper. This is not vectorization.
HEIC to WebP POST /v1/convert/heic-to-webp Converts a .heic or .heif upload to a high-quality WebP, preserving the alpha channel if present.
WebP to HEIC POST /v1/convert/webp-to-heic Converts a .webp to HEIC at maximum quality, compositing transparency onto a white background.
PDF to JPEG POST /v1/convert/pdf-to-jpeg Renders each PDF page as a JPEG at 144 DPI; single-page PDFs return a JPEG, multi-page PDFs return a ZIP with one JPEG per page.
Compress Image POST /v1/convert/compress-image Compresses PNG, JPEG or WebP in place (format unchanged): lossless-first optimization, with optional aspect-ratio-locked downscaling to a target_size_kb budget.

Shared conventions#

  • Authentication: every endpoint requires either a private API key (X-API-Key: sk_...) or a JWT token from a public key (Authorization: Bearer <jwt_token>). See Authentication.
  • Request shape: all endpoints accept multipart/form-data with a required file field plus optional output_filename and direct_download parameters. The SVG rasterization endpoints (svg-to-png, svg-to-jpeg, svg-to-webp) also accept optional width/height pixel dimensions, and compress-image accepts an optional target_size_kb budget. See Sync and Async Jobs.
  • Responses: conversions run synchronously. With direct_download=true (the default) you get the raw converted bytes; with direct_download=false you get JSON metadata including a presigned_url, object_key, filename, file_size, and conversion_time_seconds.
  • Errors and limits: endpoints return 400 for invalid or corrupt input, 401 for missing/invalid credentials, 402 when your plan's monthly ops allowance or storage limit is reached, and 413 when a file exceeds your plan's maximum file size. See Error codes.
  • Quality: conversion endpoints encode at maximum quality (not configurable). Output size is configurable where noted above: width/height on the SVG rasterization endpoints, target_size_kb on compress-image.

Frequently asked questions#

How do I convert an image format with a REST API?#

Send a multipart/form-data POST request to the matching /v1/convert/{source}-to-{target} endpoint with your image in the file field, authenticated via X-API-Key or a Bearer JWT token. By default the API responds with the raw converted file; set direct_download=false to get JSON metadata with a presigned download URL instead.

Do the SVG output endpoints vectorize my image?#

No. The JPEG, PNG, WebP, and HEIC to SVG endpoints base64-encode the raster image and embed it as a data URI inside an SVG <image> element sized to the original pixel dimensions. They do not trace the image into vector paths, and the base64 encoding adds roughly 33% to the file size.

What happens to transparency during conversion?#

It depends on the output format. Conversions to JPEG and HEIC composite transparent areas onto a white background, because those outputs are produced without transparency. Conversions to PNG and WebP preserve the alpha channel.

← markdown-to-html jpeg-to-png →