Skip to main content

Using Automatic Content Negotiation

Automatic content negotiation lets one Imgwire delivery URL return a browser-friendly image format for the current request. Use format=auto when you want Imgwire to choose the output format instead of hard-coding JPEG, PNG, WebP, or AVIF yourself.

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?format=auto&quality=auto

How negotiation works​

When a request uses format=auto, Imgwire checks the request's Accept header and chooses a supported image output format.

The practical order for modern browser delivery is:

  1. Prefer AVIF when the request accepts image/avif.
  2. Use WebP when AVIF is not accepted and the request accepts image/webp.
  3. Honor restrictive requests for browser-safe formats such as PNG, JPEG, or GIF.
  4. Use WebP for broad or missing image accept headers, such as */* or image/*.

If a request is explicitly restricted to formats Imgwire cannot deliver for that route, Imgwire can reject the request instead of returning an unsupported response.

Automatic format versus explicit format​

Use format=auto for normal browser delivery:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=auto&quality=auto

Use an explicit format when a downstream consumer requires one:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=jpeg&quality=85

Explicit format requests bypass automatic negotiation. This is useful for exports, social image workflows, and integrations that need a specific content type.

Why this helps web apps​

Without negotiation, you usually have to choose one output format for every browser or write <picture> markup with multiple sources. With format=auto, Imgwire handles the format choice at the CDN layer while your app can keep a single transformation URL pattern.

This is especially useful for:

  • CMS and user-generated images.
  • Product galleries and cards.
  • Documentation screenshots and diagrams.
  • Generated images from AI image platforms.
  • Responsive image candidates where each candidate should still use the best browser format.

Cache behavior​

Imgwire includes the resolved output format in the semantic variant cache key. That means AVIF and WebP responses for the same source image and transformation are cached as separate variants.

Keep the transformation intent stable. For example, prefer one canonical URL pattern like this:

?width=1200&format=auto&quality=auto

Avoid generating many equivalent URLs with different parameter aliases or order from different parts of your app. SDK helpers, the CLI, and MCP tools can help keep URL generation consistent.

Best practices​

  • Use format=auto for public browser-facing images.
  • Pair automatic format with quality=auto for most pages.
  • Continue to set width, height, crop, and DPR intentionally; negotiation does not choose layout dimensions.
  • Use explicit formats for exports or non-browser consumers that require a fixed content type.
  • Test with real browser requests when debugging because negotiation depends on the request headers.

Common mistakes​

  • Comparing an automatic URL in two tools without checking their Accept headers.
  • Expecting format=auto to change the original uploaded image.
  • Using format=auto for a workflow that must produce a specific file type.
  • Creating many URL shapes for the same variant instead of using one canonical SDK-generated URL.

Last updated at: May 8, 2026