Skip to main content

Imgwire Image Size Limits

Use image size limits to keep uploads predictable, avoid oversized frontend transfers, and generate delivery variants that match your application layout. Imgwire gives you controls at both upload time and delivery time.

Upload size controls​

Client API keys include a maximum_upload_bytes setting. This is the main control for browser and mobile uploads that use a Client Key.

SettingBehavior
Minimum value5120 bytes, or 5 KiB
Maximum value104857600 bytes, or 100 MiB
Default Client Key max52428800 bytes, or 50 MiB
Enforcement pointImgwire validates declared content_length against the Client Key's maximum_upload_bytes

In frontend apps, check file size before upload and send upload metadata through the SDK flow. That gives users immediate feedback and lets Imgwire reject oversized requests before the file is accepted.

const maxBytes = 50 * 1024 * 1024;

if (file.size > maxBytes) {
  throw new Error('Choose an image smaller than 50 MiB.');
}

const image = await client.images.upload(file);

Upload by URL size limit​

Server-side upload-by-URL workflows are capped at 100 MiB. This keeps remote imports bounded when Imgwire downloads the source asset from a temporary or third-party URL.

Use upload-by-URL for generated images, migrations, and trusted remote sources. For very large originals, download and inspect the file in your own backend first so you can reject, resize, or route it intentionally.

Decoded pixel limits​

File size is not the only limit that matters. Imgwire also enforces a maximum decoded image area of 250MP.

For still images, the image's decoded width multiplied by decoded height must stay under 250 megapixels. For example, a highly compressed image can still exceed the limit if its pixel dimensions are too large.

Animated GIFs are constrained by the same 250MP limit. For animated GIFs, the full decoded page span must stay under 250MP, not only the visible dimensions of one frame. A GIF can be under the 100 MiB file limit and still be too large if the animation's full page span exceeds the decoded pixel limit.

Pending upload limits​

Client API keys also include maximum_pending_uploads. Imgwire checks the number of pending images in the Environment before creating another Client Key upload.

Use this setting to protect an Environment from abandoned browser uploads or repeated attempts from public clients. The value must be at least 5 and cannot exceed the Environment's organization billing plan limit.

Transformation size limits​

Delivery transformations have their own pixel bounds. The most common dimension controls accept values from 1 through 8192 pixels:

TransformationRange
width1 through 8192 px
height1 through 8192 px
min-width1 through 8192 px
min-height1 through 8192 px

Use these transformations to deliver images at the size the UI actually needs:

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

For high-density displays, use DPR with a fixed CSS slot instead of sending a large image to every device:

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

Practical sizing strategy​

Start from the UI slot, not the original file. A full-resolution phone photo or generated image is rarely the right delivery size for a card, avatar, or documentation screenshot.

For most apps:

  • Keep original uploads large enough for future variants.
  • Use Client Key limits to prevent accidental oversized frontend uploads.
  • Use width, height, resizing_type, and crop to create layout-specific delivery variants.
  • Use format=auto&quality=auto for public image delivery.
  • Use responsive srcset variants for fluid layouts.

Common mistakes​

  • Uploading original files directly into page markup without resizing at delivery time.
  • Setting a very high frontend upload limit because only one internal workflow needs it.
  • Checking only file size and forgetting that a very large decoded image can exceed the 250MP pixel limit.
  • Assuming an animated GIF is safe because its displayed frame size looks reasonable; the full decoded page span must also stay under 250MP.
  • Using dpr=3 variants for every image regardless of visible size.
  • Confusing upload size limits with transformation dimensions. They protect different parts of the workflow.

Last updated at: May 9, 2026