Image Transformation (Beta)

Image transformation lets you fetch, resize, crop, convert, 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 contains image bytes, 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: 'center',
  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	Supported 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	inside	Controls how the source fits the requested dimensions.
imagePosition	center, attention	center	Centered or face-aware crop for cover. attention centers on detected faces, falling back to the image center when none are found.
imageFormat	webp, jpeg, png	webp	Explicit output format.
imageQuality	economy, balanced, high	balanced	Output quality preset. PNG supports balanced and high only.
imageDpr	1, 2, 3	1	Multiplies width and height for high-density displays.

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

Supported source formats are JPEG, PNG, and WebP. Choose an explicit output format from the table above.

Fit behavior

• inside preserves aspect ratio and fits within the requested box without enlarging beyond either edge.
• cover preserves aspect ratio and crops around the center or detected faces, based on imagePosition. Images are not enlarged beyond their original size.

When imageHeight is omitted, inside derives the height from the source aspect ratio. cover uses 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, 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 completed transformations. 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 advertised as non-image content returns a 4xx response.
• A format outside the plan returns 403.
• A recognized option or source image type that cannot be transformed returns the original image unchanged with X-Transform-Status: unsupported.
• If transformation fails after the original is downloaded, the response contains the original image with X-Transform-Status: failed.
• 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.

Original-image fallbacks retain the source content type, use a five-minute cache lifetime, and do not count as completed transformations. The requested dimensions and output format do not apply to those responses.

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