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 Arc XP Customer Support 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
  • WebP
  • 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, WebP, 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.

Image transformation parameters

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

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 tables describe and exemplify the path parameters available for Resizer v2.

Parameter	Description
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.
	Examples 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

Parameter	Description
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.
	Examples 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

The following tables describe and exemplify the query parameters available for Resizer v2.

Parameter	Description
auth string (required)	Security parameter. 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 API.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz

Parameter	Description
width integer (optional)	Image width in pixels. If only width is specified, the height matches the original aspect ratio.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=500

Parameter	Description
height integer (optional)	Image height in pixels. If only height is specified, the width matches the original aspect ratio.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&height=500

Note

While using width or height parameters, consider the following:

• When no dimensions are specified, the system returns a full-sized image.
• width and height are optional for Smart Crop and Focal Crop.
• width and height are required when using fit and fill parameters.
• Unspecified values in transformation parameters can cause image distortion.

Tip

To avoid image distortion, make sure to:

• Use Smart Crop.
• Provide only one dimension (width or height) for proportional scaling.

Parameter	Description
fitfill boolean (optional)	Resizes an image to fit specified dimensions while maintaining the aspect ratio. fitfill uses 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 the fitfill parameter. This parameter is incompatible with Manual, Focal, and Smart Crop.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&width=300&height=275&fitfill=true

Parameter	Description
crop string (optional)	Manual Crop. This parameter 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. Sub parameters: Name Type Required X (horizontal position) Integer No Y (vertical position) Integer No Crop width Integer Yes Crop height Integer Yes important X and Y coordinates must not exceed image dimensions. The crop parameter does not work in conjunction with focal, smart, or fitfill parameters. Pattern: {X},{Y}:{Crop width},{Crop height}
	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

Parameter	Description
focal string (optional)	Focal Crop. This parameter 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. The focal parameter requires either the width or height parameter to automatically adjust the other dimension to match the original aspect ratio. Important The focal parameter does not work in conjunction with crop, smart, or fitfill parameters. Sub parameters: Name Type X Integer Y Integer Note 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}
	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

Parameter	Description
smart boolean (optional)	Smart Crop. This parameter automatically identifies key image features and performs resizing and cropping while preserving the key image features. Smart Crop requires either the width or height parameter to automatically adjust the other dimension to match the original aspect ratio. Important The smart parameter does not work in conjunction with the crop or fitfill parameters.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=aBcdeFGhiJkLMNopqRsTuVWXyz&width=500&height=500&smart=true

Parameter	Description
quality integer (optional)	Controls output image compression level. Range: 1-100 Default: 75 (if not specified) Note A higher quality value means a bigger file size, which could impact bandwidth consumption.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&quality=75

Parameter	Description
blur integer (optional)	Applies a Gaussian blur to the image. Range: 1-100. Effect: Higher values increase image blurriness.
	Example /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&blur=5

Parameter	Description
watermark string (optional)	Overlays another image with a specified position and size on top of the source image. Sub parameters: Name Type Format Required Default Source string URL - encoded public image Yes Scale integer 1 - 100 No 100 X integer width of source image in pixels No 0 Y integer length of source image in pixels No 0 Constraints: The source image can be from Photo Center or approved third-party sources. If you wish to use third-party images as watermarks, please contact Arc XP Customer Support to have the external source added to our allow list. 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 third-party 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 Photo Center image YXWVUTSRQPONMLKJIHGFEDCBA.jpg at full-scale starting on the point [500,500] from the top-left-corner. /resizer/v2/ABCDEFGHIJKLMNOPQRSTUVWXY.jpg?auth=eNDyWY1aFcNTT1139TQbBxpXFKQ&watermark=YXWVUTSRQPONMLKJIHGFEDCBA.jpg:500,500

Parameter	Description
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. Sub parameters: Name Type Format Required Canvas width integer Width of canvas Yes Canvas height integer Height of canvas Yes Direction string One of: n, nw, ne, e, se, s, sw, w, c Yes Direction parameters The direction parameter determines the image placement within the new canvas as follows: 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}
	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.

Parameter	Description
bgcolor string (optional)	Background color. This parameter applies a hexadecimal color code to an image background. Note The background color only operates on PNGs with transparent backgrounds or images with an expanded canvas.
	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 after Resizer v2 processes your request:

Code	Meaning	Description
200	OK	Successful
400	Bad Request	Malformed parameters
403	Forbidden	- Image is unpublished - Auth is invalid - External image had 403
404	Not Found	- Arc ID doesn’t exist - 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