Image optimization API / field guide

Ship the image your interface actually needs.

A practical, vendor-aware reference for turning one source asset into the right width, format, crop, and quality at request time.

Start with the API model Compare architectures

delivery.request● ● ●

GET /image/upload/
  c_fill,w_1280,h_720/
  f_auto/q_auto/hero.jpg

HTTP/2 200
content-type: image/avif
content-length: 86kb
cache-status: hit

The syntax varies. The delivery contract should not.

01 / dimensionsMatch the slot

02 / formatNegotiate support

03 / qualityChoose by content

04 / cacheMake variants stable

The shortest correct answer

An API is the policy layer.

An image optimization API accepts a source asset plus a controlled transformation request, produces a delivery-ready variant, and caches that result close to the user. The hard part is not resizing. It is defining which variants are allowed, how clients request them, and how the system stays predictable under load.

Good default

Keep the source immutable. Generate only the widths and crops your interfaces use. Let delivery negotiate format and quality when the provider supports it. Sign or restrict any transformation surface that can create unbounded work.

01Source asset

02Variant policy

03Transform

04Edge cache

05Browser slot

The working set

Five guides. One production path.

Start with the contract, choose the operating model, wire browser markup correctly, then harden and observe the pipeline. Each guide stands alone and links to the next decision.

01 ↗Understand

The image API model

Requests, variants, caching, security boundaries, and sensible defaults.

02 ↗Evaluate

Compare architectures

Managed media platforms, origin-pull services, edge-native tools, and self-built pipelines.

03 ↗Build

Responsive delivery

Turn API variants into correct srcset, sizes, and priority hints.

04 ↗Ship

Integration checklist

Source rules, URL generation, signing, caching, observability, and rollout.

05 ↗Operate

Debug the pipeline

Wrong formats, oversized files, stale variants, signature errors, and cache misses.

06 ↗Keep learning

Reading room

Browse the published guides by the engineering decision you need to make next.

Choose by constraints

The provider is not the architecture.

A good decision begins with where originals live, who may request a transformation, how many variants the product can create, and what metadata the workflow needs. Feature lists come later.

source.ownership

Where do originals live?

Upload into a managed media platform, keep assets in your own object store, or use an origin-pull service in front of an existing library.

variant.surface

Who controls transforms?

Preset names are safer and easier to cache. Free-form URLs offer flexibility but need signing, limits, and careful cardinality control.

asset.context

What must the asset know?

If agents and applications need tags, moderation state, metadata, or search, compare the media model as well as the delivery endpoint.

Make image delivery boring.

Define a small contract, generate predictable URLs, let the browser choose the right candidate, and make every response observable.

Use the production checklist