Recommended Free Tools
Vercel’s native Image Optimization API transforms images on demand at runtime. You control it through the project’s images configuration: allowed widths, quality values, output formats, local and remote source patterns, cache retention, SVG handling, and response headers. A request succeeds only when its URL, width, quality, source response, and configured allowlists all match the rules.
This guide explains how the API works, how to configure and call it safely, why INVALID_IMAGE_OPTIMIZE_REQUEST occurs, how to control usage, and how to invalidate transformed images without needlessly deleting the cache.
What Vercel’s Image API does
Vercel describes the images property as the configuration for its native Image Optimization API, which performs on-demand optimization at runtime. In a Next.js application, the usual entry point is the next/image component. The framework requests an appropriately sized image and can serve modern formats; exact defaults depend on the Next.js version installed in your project, so check that version’s documentation before relying on an implicit value.
The optimizer fetches an approved source image, creates a variant for the requested width, quality, and format, then caches the transformed result. A typical optimized request contains three important query values:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
url: the source image URL or path.w: an integer width from the configured device and image-size lists.q: an integer quality from 1 through 100 and, when configured, from the quality allowlist.
Configuration also determines which remote hosts and local paths can be fetched, which output formats may be negotiated, whether SVG input is accepted, and how long transformed responses remain cacheable.
Configure the API with an allowlist-first policy
Keep the valid request space explicit. Broad source rules and many output variants make integration easier, but they can increase origin fetches, transformations, and cache activity. Tight lists reduce accidental work and make failures easier to diagnose.
Key configuration areas
| Area | What it controls | Why it matters |
|---|---|---|
| Device and image sizes | Permitted output widths | A request using a width outside the lists can fail. |
| Remote patterns | External hosts, protocols, ports, paths, and query constraints | The optimizer can fetch only approved remote sources. |
| Local patterns | Approved local image paths | Restricts which project assets may be optimized. |
| Qualities | Permitted quality integers | Prevents arbitrary quality variants and invalid q values. |
| Formats | Output formats the optimizer may generate | More formats can create more transformation variants. |
| Minimum cache TTL | Minimum time an optimized response may be cached | Longer retention reduces repeated work but delays source changes. |
| SVG handling | Whether SVG input is allowed | SVG is disabled by default in the documented configuration; enable it only with an appropriate security policy. |
| Response headers | Content security and content disposition behavior | Useful when images are embedded in stricter browser or download contexts. |
The official configuration reference is Vercel’s Programmatic Configuration with vercel.ts. Apply the equivalent settings in the configuration format used by your installed framework version, then deploy and test an actual optimized request.
Choose sizes deliberately
Include widths that match the layouts you really serve rather than every possible integer. A small, representative set limits variants while still covering common phones, tablets, and desktop columns. Remember that the configured device and image sizes act as allowlists: a manually constructed request with an unlisted width may return an error instead of being rounded automatically.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Restrict remote sources
Declare each image host and path you need. A remote URL that looks valid can still fail if its protocol, hostname, port, pathname, or query pattern does not match the configured rule. Avoid an unrestricted wildcard unless you have a specific reason and understand the security and cost implications.
Set quality and format policies
Quality values from 1 to 100 are syntactically valid, but a configured quality list can narrow that range. A single output format produces fewer variants; multiple formats can improve browser-specific delivery while adding transformations and cache entries. Use the smallest set that meets your visual and compatibility requirements.
How an optimized request is validated
When a request fails, inspect the complete URL and response headers before changing application code. Vercel’s error reference identifies these checks:
- Request shape: confirm that
url,w, andqare present and correctly encoded. - Width:
wmust be an integer in the configured device or image sizes. - Quality:
qmust be an integer from 1 through 100 and, if a quality allowlist exists, one of its values. - Source authorization: the URL must match a permitted local or remote pattern.
- Source response: the origin must return an
image/content type. - Response size: the source response body must remain below Vercel’s documented maximum: 300 MB generally, or 100 MB on Hobby.
These conditions are documented in Vercel’s INVALID_IMAGE_OPTIMIZE_REQUEST error reference, last updated February 9, 2026.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #3
Using Next.js and direct requests
Recommended application path
For Next.js, use next/image and provide a stable source, dimensions or a fill layout, and an appropriate sizes value. The component generates optimizer requests and serves device-appropriate variants. Confirm behavior against the Next.js release in your lockfile because defaults and configuration names can change between versions.
When inspecting a direct optimizer URL
Use browser developer tools to locate the generated image request, then verify its url, w, and q parameters. This is useful for diagnosing a failing component, but applications should normally let the framework construct the request rather than hard-coding an internal path.
Why requests fail and how to fix them
| Symptom | Likely cause | Fix |
|---|---|---|
INVALID_IMAGE_OPTIMIZE_REQUEST immediately |
Malformed or missing url, w, or q |
Inspect the encoded request and ensure width and quality are integers. |
| Width-related error | Requested width is not in the configured lists | Add the required width or change the layout/component so it requests an allowed value. |
| Quality-related error | q is outside 1–100 or not in qualities |
Use an allowed quality value and redeploy configuration if the policy needs expansion. |
| Remote image rejected | Host, protocol, port, path, or query does not match a remote pattern | Correct the pattern or use an approved source URL; do not silently open all hosts. |
| Source is not treated as an image | Origin sends a non-image content type, redirect chain, HTML error, or login page | Check the origin response with an HTTP client and ensure it returns the actual image with an image/* content type. |
| Large-source failure | Response exceeds 300 MB, or 100 MB on Hobby | Resize or compress the origin asset before optimization, or serve a smaller source. |
| SVG does not optimize | SVG input is disabled by default | Enable SVG only after reviewing your security and content-disposition requirements, or serve the SVG unoptimized. |
| Stale image after replacement | Existing transformed object remains cached | Use source-image invalidation where available, or wait for the configured cache policy. |
Managing transformations, cache, and cost
Every distinct combination of source, width, quality, and output format can create a variant. More variants generally mean more transformations and cache activity. Vercel’s cost guidance recommends reviewing cache age, formats, source patterns, quality lists, and size lists regularly.
Understand the dated pricing announcement
Vercel’s February 18, 2025 announcement described an opt-in model beginning at $0.05 per 1,000 image transformations, $0.40 per million cache read units, and $4.00 per million cache write units. Those figures are starting rates published by Vercel in that announcement, not a current quote for your account. The announcement said existing customers and new projects for existing customers were not automatically changed at that time, while new customers started on the new model; eligibility and terms can vary. Check your Vercel dashboard and current plan terms before budgeting.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Vercel’s usage documentation also notes that its announced transformation improvements, including a “60% faster transformations” claim, are vendor-reported announcement figures rather than an independent benchmark.
Practical controls
- Use a minimum cache TTL that matches how often source files change. Vercel gives
max-age=2678400(31 days) as an example when images are not expected to change within a month. - Keep output formats focused. Each additional format can add transformation work and cache variants.
- Use narrow quality and size allowlists to prevent accidental combinations.
- Use
unoptimizedselectively for assets that do not benefit from transformation, such as small images, SVGs, or animated GIFs. - Review source patterns so bots or user-controlled URLs cannot cause arbitrary origin fetches.
These recommendations are detailed in Vercel’s Managing Usage & Costs guidance and Manage and optimize usage.
Invalidate a transformed image without deleting the cache
On November 20, 2025, Vercel announced source-image invalidation through the dashboard, CLI, Function API, and REST API for plans using the new image-optimization price. Supplying the source image marks derived images stale; stale content can continue serving while revalidation runs in the background.
This differs from deleting the cache. Deletion can force regeneration on the next request, increasing latency and potentially causing an outage if the origin is unavailable. Use invalidation when the source changed but you want a controlled refresh. Follow the current interfaces in Vercel’s cache-invalidation announcement.
Operational checklist
- Record the Next.js and deployment configuration versions before changing image settings.
- Test local and remote sources, including redirects and authenticated origins.
- Exercise every intended width, quality, and format in a staging deployment.
- Check response
Content-Type, cache headers, and status codes. - Watch transformation and cache usage after launch, especially when adding formats or breakpoints.
- Document which assets deliberately use
unoptimized. - Define a source-replacement procedure that uses invalidation where your plan supports it.
Or skip the browser setup
If your goal is a clean rendered screenshot rather than responsive image delivery inside a Vercel app, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status.
One GET request returns PNG, JPEG, WebP, or PDF. The API supports full-page captures with lazy images loaded, CSS-element captures, device presets or custom viewports, dark mode, retina scale, PDF page controls, custom CSS and JavaScript, click and hide actions, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL-based caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and a usage API. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for authentication and options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThere is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Does Vercel optimize every image automatically?
No. The image must be requested through the optimizer path, usually via next/image, and its source and parameters must satisfy your configuration.
Can I allow any width from a user request?
Not when widths are configured as an allowlist. Add deliberate widths or normalize application input to an allowed value.
Should I delete the CDN cache after replacing an image?
Prefer source-image invalidation when available. It marks derived images stale and revalidates in the background instead of forcing every request to regenerate immediately.
The Bottom Line
Vercel’s Image Optimization API is predictable when you treat sizes, qualities, formats, and source patterns as explicit allowlists. Validate url, w, and q, keep origin responses small and correctly typed, monitor variant growth, and use source-level invalidation rather than indiscriminate cache deletion.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
