Image Transformation (Beta)

Image transformation lets you fetch, resize, crop, convert, rotate, and optimize a remote image through the regular CORSPROXY URL API.

Quick start

Every image request needs your API key, image=1, imageWidth, and an encoded source url:

https://corsproxy.io/?key=YOUR_API_KEY&image=1&imageWidth=640&imageHeight=360&imageFit=cover&imageFormat=webp&url=https%3A%2F%2Fexample.com%2Fphoto.jpg

The response body is the transformed image, so the URL can be used directly in an <img> element:

const source = 'https://example.com/photo.jpg';
const params = new URLSearchParams({
  key: 'YOUR_API_KEY',
  image: '1',
  imageWidth: '640',
  imageHeight: '360',
  imageFit: 'cover',
  imagePosition: 'entropy',
  imageFormat: 'webp',
  imageQuality: 'balanced',
  url: source,
});

document.querySelector('img').src = `https://corsproxy.io/?${params}`;

Free and Hobby support image transformation from browser requests. Production also supports server-side clients such as cURL, backend services, and scheduled jobs.

Parameters

Parameter	Accepted values	Default	Description
image	1	Required	Enables image transformation.
imageWidth	Integer from 1 to 4095	Required	Output width before DPR is applied. Your plan’s smaller maximum still applies.
imageHeight	Integer from 1 to 4095	Auto	Optional output height before DPR is applied.
imageFit	inside, cover, contain, fill	inside	Controls how the source fits the requested dimensions.
imagePosition	center, top, top-right, right, bottom-right, bottom, bottom-left, left, top-left, attention, entropy	center	Crop position. attention and entropy require cover or fill; all positions are ignored by fill.
imageFormat	webp, avif, jpeg, png, auto	webp	Output format. auto negotiates against the request’s Accept header and plan formats.
imageQuality	economy, balanced, high	balanced	Stable output quality preset.
imageCompression	standard, fast	standard	standard favors smaller files; fast favors encoding speed.
imageDpr	1, 2, 3	1	Multiplies width and height for high-density displays.
imageBackground	transparent, white, black	transparent	Background for padding or flattening. Transparent JPEG output is flattened onto white.
imageRotate	0, 90, 180, 270	0	Clockwise rotation in degrees.
imageFlip	none, horizontal, vertical, both	none	Mirrors the output.
imageGrayscale	0, 1	0	Set to 1 for grayscale output.

imageDpr is applied before plan limits are checked. For example, imageWidth=1280&imageDpr=2 resolves to 2560 pixels and is not available on Free.

Fit behavior

• inside preserves aspect ratio and fits within the requested box without enlarging beyond either edge.
• cover preserves aspect ratio and crops to fill both requested dimensions.
• contain preserves aspect ratio and pads as needed to match both dimensions.
• fill resizes to the exact width and height without preserving aspect ratio.

When imageHeight is omitted, inside derives the height from the source aspect ratio. Other fit modes use a square based on imageWidth.

Plan limits

Only a new, uncached derivative consumes the separate image transformation allowance. Repeating the same eligible transformation can use the shared cache without consuming another transformation.

Plan	Transformation allowance	Burst protection	Maximum source	Maximum resolved dimension	Output formats
Free	50 per UTC month	20/minute	2 MiB	1280px	WebP, JPEG, PNG
Hobby	1,000 per UTC day	100/minute	10 MiB	2560px	WebP, JPEG, PNG
Production	10,000 per UTC day	500/minute	25 MiB	4095px	WebP, AVIF, JPEG, PNG

The maximum source size in this table is specific to image transformation and is separate from the plan’s general proxy response-size limit.

Image delivery still follows your plan’s normal request and bandwidth terms. For example, a cold paid-plan transform is delivered as a regular request and also creates one image transformation; a later edge-cached delivery does not create another transformation.

Caching

Completed derivatives are eligible for shared edge and renderer caching. The cache key includes the source URL, normalized transformation options, and applicable request-header overrides, so identical requests can reuse the same derivative safely.

Production supports the existing ttl query parameter for image responses. Without a custom TTL, transformed images are returned with a long-lived public cache policy. A browser’s Disable cache option or request Cache-Control: no-cache can bypass the outer edge cache during debugging.

Request headers

Paid plans may use the existing repeated reqHeaders parameter for upstream image requests. Request-header overrides are included in cache identity.

&reqHeaders=Referer%3Ahttps%3A%2F%2Fexample.com%2F

Do not combine image=1 with extraction, data conversion, or response-header rewrite parameters.

Errors and quota behavior

• Invalid transformation parameters return a 4xx response with a JSON error.
• A source response that is not a supported image returns a 4xx response.
• An unsupported negotiated format returns 406; a format outside the plan returns 403.
• Burst protection returns 429 with Retry-After.
• When the longer-period image allowance is exhausted, CORSPROXY returns 429 with Retry-After by default.
• In the console, you can opt into returning the original source image unchanged instead. Those responses use X-Transform-Status: quota-exceeded to indicate that the requested transformation was not applied.

Because this feature is in beta, monitor the response status, Content-Type, and X-Transform-Status rather than assuming every successful response was transformed.