How to Process Image Uploads in a SaaS App

01

Start with the upload contract

The first useful design decision is deciding what the upload means. Is the uploaded file the canonical source of truth? Is it just a temporary input to a processing step? Can the user re-download it later? Can they apply a different background, crop, or format without uploading again?

For image processing in a SaaS app, I like to separate the upload into three artifacts: the original source, a working input, and one or more outputs. Sometimes the original and working input are the same object. Sometimes they are not. Keeping the distinction clear prevents a lot of later confusion.

This contract also answers a common API question: should you send a multipart file, an image URL, or base64? For direct user uploads, multipart image_file is the best default. It avoids base64 expansion, works naturally from browsers and workers, and lets the processor receive the original file bytes. Use image_url when the source already lives in object storage or a third-party media system. Avoid base64 unless your platform forces it, because it makes payloads larger and tends to push more data through memory.

02

The Studio version

Studio is intentionally direct because it is an interactive tool. A user chooses one image, waits for that one image, and sees the result immediately. That makes a synchronous request acceptable as long as the UI can show progress, surface errors, and abandon stale results when the user uploads a different file.

The flow is still doing more than "send whatever the browser gave us." Studio checks that the file is not empty, enforces the public upload limit, accepts only known image MIME types, reads the first bytes to reject obviously invalid files, converts HEIC or HEIF to a high-quality JPEG in the browser, and opens the image with createImageBitmap to reject dimensions that are too small or wildly large.

const formData = new FormData();
formData.append("image_file", fileForProcessing, fileForProcessing.name || "upload");
formData.append("format", "png");
formData.append("channels", "rgba");
formData.append("size", "full");

const response = await fetch("/api/process-image", {
  method: "POST",
  headers: await authHeaders(),
  body: formData,
});

if (!response.ok) {
  throw new Error(await readProcessImageError(response));
}

const blob = await response.blob();
processedObjectUrl = URL.createObjectURL(blob);

The internal /api/process-image endpoint is a proxy, not the image processor itself. That matters. The browser should not hold the private processor API key, and the app needs a place to enforce auth, plan state, daily usage limits, request shape, and upstream error handling.

export async function POST({ request }) {
  const contentLength = Number(request.headers.get("content-length") || 0);

  if (contentLength > MAX_PROXY_BODY_BYTES) {
    return json({ error: "Payload too large" }, { status: 413 });
  }

  const contentType = request.headers.get("content-type") || "";
  if (!contentType.toLowerCase().includes("multipart/form-data")) {
    return json({ error: "Expected multipart form data with image_file" }, { status: 415 });
  }

  const upstream = await fetch(PROCESSOR_URL, {
    method: "POST",
    headers: copyHeadersForUpstream(request),
    body: request.body,
    duplex: "half",
  });

  if (!upstream.ok) {
    throw new UpstreamResponseError(upstream.status, await readUpstreamError(upstream));
  }

  const upstreamContentType = upstream.headers.get("content-type") || "image/png";
  if (!upstreamContentType.toLowerCase().startsWith("image/")) {
    throw new Error("Processor did not return an image");
  }

  return new Response(upstream.body, {
    headers: {
      "Content-Type": upstreamContentType,
      "Cache-Control": "no-store",
    },
  });
}

03

Original, compressed, or resized?

The short answer: send the original when it fits the processor limits and the output quality matters. Compress or resize only when the original is too large, too slow, in a browser-unfriendly format, or much higher resolution than the product can use.

Background removal is especially sensitive to this choice because the interesting information is often on the edge: hair, glass, product shadows, thin straps, spokes, labels, texture, and low contrast boundaries. Heavy JPEG compression can create blocks around those edges. Aggressive downscaling can turn a detailed boundary into mush. You may save time on the upload and then pay for it in output quality.

For BackgroundErase specifically, the normal API limit is 30 MB and decoded images may not exceed 100,000,000 pixels. That means a 12 MB product JPEG should usually go through untouched. A 48 MB phone photo might need a high-quality re-encode or a long-edge cap before processing. A 12,000 by 12,000 image needs dimension handling even if the file happens to compress under the byte limit.

Also be careful with transparent PNGs, screenshots, logos, and text overlays. Converting those to JPEG can destroy the exact edges that made the file useful. If your app accepts mixed image types, do not apply one compression rule to all of them. Branch by format, pixel dimensions, file size, and expected output.

04

Keep work out of fragile requests

A synchronous request is simple, and sometimes that simplicity is the right tradeoff. Studio can do it because the user is knowingly waiting for one image. Most SaaS product flows should use a job boundary sooner than people expect.

The upload request should be responsible for accepting the file, validating the obvious things, storing the source, and creating a record. The processing worker should be responsible for calling the image API, writing outputs, and moving the record through state. That separation gives you retries, better logs, and a UI that survives a refresh.

Browser upload
  -> create upload record
  -> store original object
  -> enqueue processing job
  -> worker creates result object
  -> update record to ready
  -> browser polls, subscribes, or receives callback

The biggest mistake is tying the entire feature to the browser staying connected. Mobile browsers suspend tabs. Users double-click. Corporate networks kill long requests. Serverless functions have timeouts. A queue helps prevent this by normalizing obscure edge cases across the board.

05

Storage and idempotency

Once an upload can outlive the request, storage layout matters. I would avoid scattering original files and results under unrelated keys. Put everything for one upload or job under a predictable prefix so support, cleanup, and reprocessing are boring.

uploads/upl_01hzk8/raw/original.jpg
uploads/upl_01hzk8/working/input.jpg
uploads/upl_01hzk8/results/background-removed.png
uploads/upl_01hzk8/results/mask.png
uploads/upl_01hzk8/metadata.json

The database record is just as important as the object keys. It should know which source was uploaded, which working derivative was processed, which options were used, where the result landed, and whether the job can be safely retried.

{
  "id": "upl_01hzk8",
  "userId": "user_123",
  "status": "processing",
  "input": {
    "originalKey": "uploads/upl_01hzk8/raw/original.jpg",
    "workingKey": "uploads/upl_01hzk8/working/input.jpg",
    "sha256": "d0f1f7..."
  },
  "output": {
    "format": "png",
    "channels": "rgba",
    "resultKey": null
  },
  "attempts": 1,
  "createdAt": "2026-07-05T15:40:00.000Z",
  "updatedAt": "2026-07-05T15:40:03.000Z"
}

Idempotency is what keeps retries from creating nonsense. If the user retries the same upload with the same options, you should be able to either return the existing result or safely overwrite the same output key. Use a stable upload ID, an input hash, and a normalized options hash. Do not use "current timestamp plus random filename" as your only source of truth unless you enjoy archaeology.

06

Validation and failure states

Upload validation should happen in layers. Client-side checks make the product feel immediate, but server-side checks are the ones that protect the system. The browser can tell a user "that file is too large" before the upload starts. The server still needs to enforce byte limits, content type, auth, quota, and processor options.

A good user-facing flow separates "you can fix this" from "we are still working on it." Too large, unsupported, corrupt, and too small are user-fixable. Rate limits, upstream timeouts, and transient processor errors are system states. That distinction changes the button copy, the retry behavior, and the support burden.

07

Production checklist

The shape I would start with depends on the product moment. If you are building a fast interactive editor, the Studio pattern is fine: validate hard, post multipart, stream the response, and keep the UI honest about loading and errors. If the image belongs to a durable business object, introduce storage and jobs before users depend on the result.