offload.runoffload.run

Image Optimization

Resize, convert, and compress images for faster page loads.

When to use it

User-uploaded images are rarely sized or encoded for the web. The compress-image job resizes them to sensible dimensions and re-encodes to a modern format like WebP or AVIF, typically cutting file size by 60–80% with no visible quality loss.

Basic usage

import { Offload } from '@offload-run/sdk'

const offload = new Offload({ apiKey: process.env.OFFLOAD_API_KEY })

const job = await offload.enqueue('compress-image', {
  input: 'https://example.com/photo.png',
  options: {
    format: 'webp',
    maxWidth: 1600,
    quality: 82,
  },
})

console.log('Job ID:', job.id)

Options

format

Output format: webp (default), avif, jpeg, or png.

quality

1–100. Lower means smaller files. 80–85 is visually lossless for most photos. Ignored for png.

maxWidth / maxHeight

Constrain dimensions while preserving aspect ratio. The image is only scaled down, never up.

SVG handling

SVG inputs are sanitized before processing — scripts and external references are stripped — so you can safely accept user-uploaded vectors. Gradients, clip paths, and inline data URIs are preserved.

Responsive variants

To build a srcset, enqueue one job per width and collect the results:

const widths = [640, 1024, 1600]

const jobs = await Promise.all(
  widths.map((maxWidth) =>
    offload.enqueue('compress-image', {
      input: 'https://example.com/photo.png',
      options: { format: 'webp', maxWidth },
    }),
  ),
)

console.log(jobs.map((job) => job.id))

Tips

  • Prefer aviffor the smallest files when your audience's browsers support it, with a webp fallback.
  • Image jobs are fast — polling GET /jobs/:id is fine, but webhooks still scale better under load.
  • Result URLs are signed and expire after one hour; re-fetch the job for a fresh link rather than storing the URL long-term.
PreviousVideo Compression