Transform Images with Resizer v2

Photo Center stores images at their highest resolution, making it essential to use Image Resizer v2 for web display optimization.

For example, images that appear next to a story on a search engine results page must be thumbnail-sized so that the page loads quickly; they might also need to have a consistent shape, regardless of their original aspect ratios.

Instead of storing multiple versions of the same image, Arc XP uses a just-in-time image resizing service to create transformed images as needed, known as transformations. Then, Arc XP Content Delivery Network (CDN) stores and distributes these transformed images optimizing page loading times.

This document guides you through Resizer’s v2 key features, supported image formats, and the most common transformation use cases.

Tip

Use this document and the How to Preview Image Transformations guide to test the most common transformations use cases. Contact your Technical Account Manager if this guide does not mention your use case.

Resizer v2 Key Features

Resizer v2 has the following key features:

• Provides a dynamic image resizing and transformation service.
• Enables SEO-friendly image naming capabilities to enhance site performance.
• Brings built-in authentication token system included in the image ANS.
• Enables automatic CDN distribution for optimized delivery.

Supported Image Formats

Resizer v2 supports the following image formats:

• Internal Photo Center images
• External images:
  • High-quality JPEGs
  • PNGs (recommended for images requiring transparency)
  • GIFs
  • Any standard web format

Important

Resizer v2 does not support the following formats: Photoshop (PSD), RAW, and SVG images.

Dynamic Format Selection

Photo Center accepts image uploads and automatically optimizes delivery through Arc XP’s integration with our CDN provider. This system ensures optimal image format delivery based on client capabilities.

Upload Process

Users upload JPEG, GIF, PNG, BMP, TIFF, or ICO files to Photo Center. The original asset is preserved as the source image, ensuring maximum compatibility and quality retention.

Image Delivery

When a client requests an image, the CDN automatically evaluates the client’s capabilities and delivers the most efficient supported format. For JPEGs, the format selection is as follows:

• AVIF: Delivered to modern browsers with AVIF support, providing superior compression and quality

• WebP: Served to browsers supporting WebP but not AVIF, offering improved efficiency over JPEG

• JPEG: Provided as a fallback for clients without WebP or AVIF support

This process occurs transparently without requiring any action from content creators or developers. The CDN handles format selection and conversion automatically, optimizing both performance and visual quality.

Transformation Guide

Learn how to build transformation URLs to resize, crop, and modify your images. This guide covers the following:

• Resize v2 Base Path
• Path Parameters
• Query Parameters
• Resize Transformations
• Crop Transformations
• Additional Transformations

Resizer v2 Base Path

All image transformations start with the following base path:

/resizer/v2/

Important

Always use lowercase “v” in the base path, as it is case-sensitive.

Path Parameters

The following are the elements that identify and grant access to your images:

• Source
• SEO Filename

Source

String (Required)

Original image to perform resize operations on. The source can reference an internal image from the Photo Center or a full external URL.

Note

You must include the protocol (HTTP/HTTPS) if you use an external domain. The whole string must be URL-encoded.

Source Examples:

• Internal Photo Center image: Arc ID of an image from Photo Center. Ensure to include the extension as it appears in the CloudFront URL.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg`

• External non-Photo Center image: Encoded URL of a public external image, including the protocol.

/resizer/v2/https%3A%2F%2Fi.picsum.photos%2Fid%2F582%2F200%2F300.jpg

SEO filename

String (Optional)

SEO-friendly filename to add descriptive text to your image URLs for better search engine visibility. This parameter appears before the Arc ID for internal images. You must use alphanumeric characters and dashes in the filename.

URL Building Patterns:

Dynamically construct resizer URLs using SEO-friendly photo metadata:

• With extension: "/resizer/v2/" + photo.seo_filename + "-" + photo._id + "." + photo.url.split(".").pop()
• Without extension: "/resizer/v2/" + photo.seo_filename + "-" + photo._id

Example URL with SEO Filename:

/resizer/v2/some-image-ABCDEFGHIJKLMNOPQRSTUVWXY.jpg

Query Parameters

Security

Auth

String (Required)_

Validate your image source using a Base64-encoded SHA256 security code. The auth code checks only the source image and ignores SEO filenames and query parameters.

Note

For internal images, get this auth code from the Security Auth field in your image ANS. For external images, use the Signing Service.

Auth Example:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz

Resize Transformations

Change image dimensions while maintaining quality using the following parameters:

• Width/Height
• Fit/Fill

Width/Height

Integer (Optional)

Resizes an image to the desired output width or height, considering the following data:

• No Dimensions Specified: The system returns a full-sized image.
• Width-only: Height matches the original aspect ratio.
• Height-only: Width matches the original aspect ratio.
• Specific transformations have unique dimensional requirements.

Dimension Considerations:

• Width or height are optional for Smart Crop and Focal Crop.
• Width and height are required for Fit/Fill.
• Unspecified transformation may cause image distortion.

Distortion Prevention

To prevent image distortion consider the following:

• Use Smart Crop to prevent stretching.
• Provide only one dimension for proportional scaling.

Width and Height Examples:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=500

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&height=500

Fit/Fill

Boolean (Optional)

Resizes an image to fit specified dimensions while maintaining the aspect ratio, using a blurred version of the original image to fill any transparent space at the edges.

important

Both width and height must be specified to use this fit/fill.

This feature is incompatible with Manual, Focal, and Smart Crop.

Fit/Fill Example:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&width=300&height=275&fitfill=true

Crop Transformations

Adjust your image framing and aspect ratios with the following features:

• Manual Crop
• Focal Crop
• Smart Crop

Manual Crop

String (Optional)

Manual Crop enables precise cropping of the source image by specifying the exact position and dimensions. The crop coordinates (X, Y) are measured from the image’s top-left corner.

Important

Manual Crop does not work in conjunction with Focal Crop, Smart Crop, or Fit/Fill parameters.

Parameters:

Name	Type
X (horizontal position)	Integer
Y (vertical position)	Integer
Crop Width	Integer
Crop Height	Integer

Manual Crop requirements:

• Both crop width and crop height are required parameters.
• X and Y coordinates must not exceed image dimensions.

Pattern:

{X},{Y}:{Crop Width},{Crop Height}

Manual Crop Examples:

Create a 500x500 crop of the top-left corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&&crop=0,0:500,500

Create a 400x100 vertical crop starting at the point [1023,705] from the top-left corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&&crop=1023,705:400,100

Create a 640x480 crop starting at the point [250,365] from the top-left corner, and resize the result to 350px wide.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=350&crop=250,365:640,480

Focal Crop

String (Optional)

Focal Crop enables precise control over the center point of your crop while maintaining aspect ratio integrity. This transformation is ideal when you must ensure that specific image elements remain visible after resizing.

Focal Crop requires only the width or height parameter and automatically adjusts the other dimension to match the original aspect ratio.

Important

Focal Crop does not work in conjunction with Manual Crop, Smart Crop, or Fit/Fill parameters.

Parameters:

Name	Type
X	Integer
Y	Integer

Focal Crop Considerations:

• If the requested dimensions match the original aspect ratio, the image resizes normally without cropping.
• When cropping is necessary (aspect ratio changes), the system preserves as much of the focal point area as possible.

Pattern:

{X},{Y}

Focal Crop Examples:

Create a 500x500 crop focused on the point [1337,709] from the top-left corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=500&height=500&focal=1337,709

Create a 400x100 vertical crop focused on the point [692,466] from the top-left corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=400&height=100&focal=692,466

Smart Crop

Boolean (Optional)

Smart Crop automatically identifies and preserves key image features when resizing and crops around them.

Smart Crop requires only the width or height parameter and automatically adjusts the other dimension to match the original aspect ratio.

Parameters:

width or height: Integer (Required)

Important

You cannot use Smart Crop with Manual Crop or Fit/Fill parameters.

Smart Crop Example:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=500&height=500&smart=true

Additional Transformations

Ensure image quality and apply filters, rotations, and other image effects with the following features:

• Quality
• Blur
• Watermark
• Canvas
• Background Color

Quality

Integer (Optional)

Controls output image compression level.

• Range: 1-100 (integer).
• Default: 75 if not specified.

Quality Example:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&quality=75

Blur

Integer (Optional)

Applies a Gaussian blur to the image.

• Effect: Higher values increase image blurriness.
• Range: 1-100.

Example:

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&blur=5

Watermark

String (Optional)

Overlays another image with a specified position and size on top of the source image.

Parameters:

Name	Type	Format	Default
Source	String	URL - encoded public image	Required
Scale	Integer	1 - 100	100
X	Integer	0 - width of source image	0
Y	Integer	0 - length of source image	0

Constraints:

• The source image must be publicly accessible on the internet.
• Scale adjusts the overlay image’s size as a percentage of the main image’s width, keeping its original shape.
• If the values for X/Y exceed the original image’s width or height, the operation fails, and the original image returns.

Pattern:

{Source}:{Scale}:{X},{Y}

Examples:

Place external image https://i.picsum.photos/id/582/200/300.jpg at 35% scale starting on the point [0,250] from the top-left-corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&watermark=https%3A%2F%2Fi.picsum.photos%2Fid%2F582%2F200%2F300.jpg:35:0,250

Place external image https://i.picsum.photos/id/582/200/300.jpg at full-scale starting on the point [500,500] from the top-left-corner.

/resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&watermark=https%3A%2F%2Fi.picsum.photos%2Fid%2F582%2F200%2F300.jpg:500,500

Canvas

String (Optional)

Expands the canvas of an image by adding borders or extra space. The canvas dimensions must be larger than the original image. Otherwise, the image gets cropped.

Parameters:

Name	Type	Format	Default
Canvas Width	Integer	Width of canvas	Required
Canvas Height	Integer	Height of canvas	Required
Direction	String	One of: n, nw, ne, e, se, s, sw, w, c	Required

Canvas Considerations:

The direction parameter determines the image placement within the new canvas as follows:

Direction Parameter	Image Placement
n	Centered horizontally along the top of the canvas.
nw	Top-left corner.
ne	Top-right corner.
e	Centered vertically along the right of the canvas.
se	Bottom-right corner.
s	Centered horizontally along the bottom of the canvas.
sw	Bottom-left corner.
w	Centered vertically along the left of the canvas.
c	Centered vertically and horizontally to the canvas.

Pattern:

{Width},{Height}:{Direction}

Canvas Examples:

ABCDEFGHIJKLMNOPQRSTUVWXY.jpg is a 1920x1080 image

YXWVUTSRQPONMLKJIHGFEDCBA.png is a 600x260 image

Expand the canvas by 100 pixels on both dimensions to produce a white/empty border. Example image

/resizer/v2/ALJL6W5WXRB4JHBRF7QSZVQ6OA.jpg?auth=47adf8844460ce7e80d75fbc581cade16be8097487dad63851e189d5df1a48d3&canvas=2120,1180:c

Add a second image YXWVUTSRQPONMLKJIHGFEDCBA to the right of the original image to make a 3840x1080 composite. Example image

/resizer/v2/ALJL6W5WXRB4JHBRF7QSZVQ6OA.jpg?auth=47adf8844460ce7e80d75fbc581cade16be8097487dad63851e189d5df1a48d3&canvas=3840,1080:w&watermark=HYJMOUDHOZH35PYDRAI75ZSFW4.png:50:1920,200

Add a second image YXWVUTSRQPONMLKJIHGFEDCBA to the left of the original image to make a 3840x1080 composite. Example image

/resizer/v2/ALJL6W5WXRB4JHBRF7QSZVQ6OA.jpg?auth=47adf8844460ce7e80d75fbc581cade16be8097487dad63851e189d5df1a48d3&canvas=3840,1080:e&watermark=HYJMOUDHOZH35PYDRAI75ZSFW4.png:50:0,200

Add a second image YXWVUTSRQPONMLKJIHGFEDCBA to the right of the original image and resize that output to 600 pixels wide. Example image

/resizer/v2/ALJL6W5WXRB4JHBRF7QSZVQ6OA.jpg?auth=47adf8844460ce7e80d75fbc581cade16be8097487dad63851e189d5df1a48d3&width=600&canvas=3840,1080:w&watermark=HYJMOUDHOZH35PYDRAI75ZSFW4.png:50:300,30

Tip

In the last example, the Canvas width is 300 instead of 1920 because the &width=600 is processed first, so the XY coordinates now observe a canvas of 600x600.

Background Color

String (Optional)

Hexadecimal color code applied to an image background.

Note

The background color only operates on PNGs with transparent backgrounds or images with an expanded canvas.

Background Examples:

Apply a black background to a transparent PNG. Example image

/resizer/v2/O4EKZIBVSVAUJM757BOOFSQ3RA.png?auth=9c21aeaf0c070a6f1b7aeb0ecf8babec20e00e97881f9e2aa2ce1e0b4e477f8d&bgcolor=0000000

Add a red border by expanding the canvas by 100 pixels on both dimensions. Example image

/resizer/v2/ALJL6W5WXRB4JHBRF7QSZVQ6OA.jpg?auth=47adf8844460ce7e80d75fbc581cade16be8097487dad63851e189d5df1a48d3&canvas=2120,1180:c&bgcolor=ff0000

Response Codes

The following table describes the status codes meaning after Resizer v2 processes your request:

Status	Meaning	Description
200	OK	Successful
400	Bad Request	Malformed parameters
403	Forbidden	Image is unpublished or; Auth is invalid or; External image had 403
404	Not Found	Arc ID doesn’t exist or; External image reference had 404
500	Internal Server Error	Image Manager/EdgeWorker error
502	Bad Gateway	Upstream error for source image retrieval
504	Gateway Time-out	Upstream timeout for source image retrieval