AIO Parameters

Refer this page to instruct AIO to resize/crop/merge the image based on the value provided in querystring.

Note: For demo purpose, we will be using www.n7.io domain as an example.

Prerequisite#

You must have a domain configured on Nitrogen
You must have AIO enabled, please refer this article .

You can add the following query parameters in the image URL to scale the image based on width/height, to crop, to cut, to merge, or to serve original image without optimizing it:

AIO parameters#

Serve Original Image#

Query Parameter: aio=noopt;

Description: This delivers the unoptimized original image, maintaining its original dimensions. This is useful when you want users to zoom in and see minute details.

Example: This displays the original image:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=noopt;

Serve optimized image#

Serve optimized image without any transformations#

Query Parameter: N/A

Description: Serves the optimized image with original dimensions of the image - without any resizing or modifications.

Example:
https://www.n7.io/aio_examples/test_img_2.jpeg

Serve Optimized Image in given format#

Query Parameter: aio=f-<format>;

Description: This delivers the optimized version of image in given format.

Example: This displays the optimized image in jpeg format:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=f-jpeg;

Available values:

avif
webp
original image format e.g. here jpeg

Scale image#

Scale by Width#

Query Parameter: aio=w-<number>;

Description: This resizes the image to the specified width while keeping the aspect ratio intact. This is typically used to display the same image with different widths on various pages.

Example: This resizes the image to a width of 200 pixels:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-200;

Scale by Height#

Query Parameter: aio=h-<number>;

Description: This resizes the image to the specified height while maintaining the aspect ratio. This is commonly used to display the same image with different heights on various pages.

Example: This resizes the image to a height of 200 pixels:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=h-200;

Set image sharpness#

Sharpen Image#

Query Parameter: aio=sharp;

Description: This operation sharpens the image.

Example:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=sharp;

Notes: Currently sharpening algorithm and amount being applied is default and not manageable through AIO query-parameter.

Blur Image#

Query Parameter: aio=blur-<strength>;

Description: This operation blurs the image based on provided strength within range [0-100]. Where, 0 - No Blur & 100 - Maximum Blur

Example:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=blur-100;

Serve image with provided DPR#

Query Parameter: aio=dpr-<number>;

Description: This operation serves the image with dimensions based on the provided DPR value [1, 2]. Where, 1 - original dimensions & 2 - doubled dimensions.

Example:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=dpr-2;

Cut#

Query Parameter: aio=w-<number>;h-<number>;cut,<optional-cut-parameters>;

Description: This documentation explains the various image cropping operations available in Nitrogen. All these operations currently only work with the “cut” operation type.

Example: Here image is cropped by given dimensions (by default from center)
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-400;cut;

Crop by Location#

Query Parameter: cut,top;
This operation cuts a rectangular region from the top of the image. The size of the rectangle is determined by the provided width and height.
- Example: This URL will return a 400x200 pixel image cropped from the top portion of the original image.
  https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-200;cut,top
Query Parameter: cut,left;
This operation cuts a square region from the left of the image. The size of the square is determined by the provided width and height.
- Example: This URL will return a 400x400 pixel image cropped from the left of the original image.
  https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-200;cut,left
Query Parameter: cut,top-left;
This operation cuts a rectangular region from the top-left corner of the image. The size of the rectangle is determined by the provided width and height.
- Example: This URL will return a 200x150 pixel image cropped from the top-left corner of the original image.
  https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-200;cut,top-left
Available values:

Crop by Custom Coordinates#

Query Parameter: cut,custom

Description: This operation allows you to specify the exact location and size of the cropped region. You provide the width and height as usual, but additionally specify the starting x and y coordinates (defaults to 0,0) from which the cropping should begin.

Example: This URL will return a 300x300 pixel image cropped from the original image, starting 300 pixels from the right and 50 pixels down from the top-left corner.
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-200;h-200;cut,custom,x-410,y-760;

Crop at face#

Query Parameter: cut,face / cut,part

Description: These operations attempt to intelligently crop a region of the image that might contain a face or other significant element.
It uses a static default of 50% for X (horizontal center) and 20% for Y (20% down from the top).

Example: This URL will return a 400x200 pixel image automatically cropped based on static defaults.
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-200;h-300;cut,face;

Crop#

Query Parameter: aio=w-<number>;h-<number>;crop;

Description: This operation resizes the image to the specified width (w) and height (h), while maintaining the original aspect ratio. If the original image proportions don’t match the requested dimensions, it will be cropped to fit the new size.

Example: This resizes this image to 400 pixels wide and 400 pixels high, maintaining the aspect ratio and cropping any excess if necessary:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-400;crop;

Important notes for all `cut` and `crop` operations#

All cropping operations currently only work with the “cut” operation type.
For custom cropping (cut,custom), ensure the provided x and y coordinates stay within the image boundaries (0,max < x,y < source_width, source_height).

Debug feature for all cut and crop operations#

Query Parameter: explain;

explain: This operation is for debugging purposes only and does not modify the image. It displays a rectangle on the original image to visualize the sample area that would be affected by a specific “cut” operation.

Example: https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-400;h-400;cut;explain;
This URL shows the original image with a rectangle indicating the area that would be cropped by the cut operation.

Combine Images#

Query Parameter: aio=append,image=(url=https://www.n7.io/aio_examples/test_img_2.jpeg);

Description: This operation allows you to combine multiple images into a single image.

Example: This combines the image1 with another image2 by placing them side-by-side
https://www.n7.io/aio_examples/test_img_3.jpeg?aio=append,image=(d=h,url=https://www.n7.io/aio_examples/test_img_2.jpeg);

Available values:

d=h (default): Images are appended horizontally (side-by-side).
d=v (not yet supported): Images would be appended vertically (top-to-bottom).

Updating image content#

Watermark#

Query Parameter: aio=watermark(url=<image-url>,pos=<position>,scale=<number>,opacity=<number>);

Description: Overlays a watermark image (such as a logo) on top of the image. All parameters are supplied inside watermark(...) as comma-separated key=value pairs (the same style as append). Only url is required; by default the watermark is placed in the center of the image at its original size.

url — the watermark image URL (required).
pos (or position) — where to place the watermark: top, bottom, left, right, top-left, top-right, bottom-left, bottom-right.
scale — resizes the watermark to the given percentage (1–100) of the base image width.
opacity — watermark opacity as a percentage (1–100).

Example: This overlays a watermark in the bottom-right corner, scaled to 20% of the image width at 70% opacity:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=watermark(url=https://www.n7.io/aio_examples/test_img_3.jpeg,pos=bottom-right,scale=20,opacity=70);

Note:

The watermark image URL must be publicly reachable by AIO.
scale and opacity accept values from 1 to 100; values outside this range are ignored (original size / full opacity).
The watermark image URL must not contain a comma (,) — commas separate the parameters.

Text Overlay#

Query Parameter: aio=text(value=<text>&size=<px>&color=<hex>&pos=<position>);

Description: Draws a text label on top of the image. The parameters inside text(...) are separated by &:

value (or text) — the text to render.
size — font size in pixels (default 48).
color — text color as a 3- or 6-digit hex value without # (default white).
pos (or position) — placement: top, bottom, left, right, top-left, top-right, bottom-left, bottom-right (default: center).

Example: This draws “SALE NOW” in black (000000) at the top of the image:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=text(value=SALE%20NOW%26size=64%26color=000000%26pos=top);

Notes: (URL encoding is required):

The text(...) parameters are separated by &, which is also the URL query separator, and the text may contain spaces. You must URL-encode these characters in the final URL:
- space → %20
- & → %26
For example, text(value=SALE NOW&size=64&color=000000&pos=top) must be written in the URL as text(value=SALE%20NOW%26size=64%26color=000000%26pos=top).

Fill (Pad to Fit)#

Query Parameter: aio=w-<number>;h-<number>;fill; or aio=w-<number>;h-<number>;fill.<hex-color>;

Description: This resizes the image so it fits entirely within the given width and height while preserving the aspect ratio, then pads the leftover space with a background color. Unlike crop, no part of the image is ever cut off. Use fill for a white background, or fill.<hex-color> to set the padding color as a 3- or 6-digit hex value (without #).

Example: This fits the image into a 500x300 canvas and fills the empty space with red (ff0000):
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-500;h-300;fill.ff0000;

Notes:

fill without a color pads with white.
The color is a hex value without a leading # (e.g. fill.eeeeee, fill.f00).
The whole image is always visible; only the padding area changes with the fill color.

Presets#

Query Parameter: aio=preset.<name>;

Description: A preset is a named, reusable shortcut for a group of AIO operations, configured per domain. Using preset.<name> in the URL expands to the full operation string defined for that name — keeping URLs short and letting you change the transformation for many images by editing a single preset.

Example: If your domain defines a preset named card as w-500;h-300;fill.ff0000, then:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=preset.card;
is equivalent to:
https://www.n7.io/aio_examples/test_img_2.jpeg?aio=w-500;h-300;fill.ff0000;