Syntax and Examples

Before you begin

Set up the IMQuery transformation as described in IMQuery.

How to

  1. Use this table to learn how to modify image URLs using an IMQuery string. The table includes links to more information for each transformation, followed by the syntax, and an example that a developer can use in a URL.
    These examples use the required parameters for each transformation. For a complete list and details about all the available parameters see the Transformation types section in the Image Manager API v2 documentation.
    Note: IMQuery transformation parameters are case sensitive.
  2. Open a browser and go to the URL of the image you want to change using one of the transformations in the table.
  3. Add the IMQuery string to your image URL to view the transformation.
  4. You can include multiple transformations in one IMQuery string. For example:
    https://www.example.com/image.jpg?im=Resize=(400,400);BackgroundColor=abab50
    Note: Review these guidelines when creating an IMQuery transformation with multiple transformations:
    • include a semi-colon between each transformation
    • transformations occur in order in which they appear
    • URL length restrictions imposed by browsers apply to IMQuery strings
    • the length and complexity of an IMQuery string impacts the request processing time
    If...Then...
    Append Use this syntax:

    <ImageURL>?im=Append,image=(url=<url_to_appended_image>)

    For example:

    https://www.example.com/image.jpg?im=Append,image=(url=https://www.example.com/image2.jpg)

    For a complete list of transformation options see the Append section in the Image Manager API v2 documentation.
    Aspect Crop Use this syntax:

    <ImageURL>?im=AspectCrop,(width,height),xPosition=<horizontal_position>,yPosition=<vertical_position>

    For example, to center the cropped area while changing the image to achieve the requested aspect ratio:

    https://www.example.com/image.jpg?im=AspectCrop=(1,3),xPosition=.5,yPosition=.5

    To expand the image canvas to achieve the requested aspect ratio and position the fully transparent pixels at the above the image:

    https://www.example.com/image.jpg?im=AspectCrop=(1,3),allowExpansion,yPosition=1
    Background Color Use this syntax:

    <ImageURL>?im=BackgroundColor,color=<hex_color_value>

    For example:

    https://www.example.com/image.jpg?im=BackgroundColor,color=00ff00

    For a complete list of transformation options see the BackgroundColor section in the Image Manager API v2 documentation.
    Blur Use this syntax:

    <ImageURL>?im=Blur

    For example:

    https://www.example.com/image.jpg?im=Blur
    Use this syntax to specify the blur strength:

    <ImageURL>?im=Blur=<blur_strength>

    For example:

    https://www.example.com/image.jpg?im=Blur=2

    For a complete list of transformation options see the Blur section in the Image Manager API v2 documentation.
    Watermark/Composite Use this syntax:

    <ImageURL>?im=Composite,image=(url=<url_to_the_image_text_or_shape)

    For example:

    https://www.example.com/image.jpg?im=Composite,image=(url=https://www.example.com/image2.jpg)

    For a complete list of transformation options see the Composite section in the Image Manager API v2 documentation.
    Contrast Use this syntax:

    <ImageURL>?im=Contrast,contrast=<contrast_level>

    For example:

    https://www.example.com/image.jpg?im=Contrast,contrast=0.5

    For a complete list of transformation options see the Contrast section in the Image Manager API v2 documentation.
    Crop Use this syntax:

    <ImageURL>?im=Crop,width=<width_to_crop>,height=<height_to_crop>

    For example:

    https://www.example.com/image.jpg?im=Crop,width=150,height=100
    Use this syntax to apply the Crop transformation using the size shortcut:

    <ImageURL>?im=Crop,size=(<width_to_crop>,<height_to_crop>)

    For example:

    https://www.example.com/image.jpg?im=Crop,size=(150,100)
    Use this syntax to apply the Crop transformation using the rect shortcut for xPosition, yPosition, width, and height. We've also included the gravity parameter to specify the placement or region of the crop within the image:

    <ImageURL>?im=Crop,rect=(<xPostion>,<yPosition>,<width_to_crop>,<height_to_crop>),gravity=<placement_in_image>

    For example:

    https://www.example.com/image.jpg??im=Crop,rect=(0,0,100,100),gravity=Center

    For a complete list of transformation options see the Crop section in the Image Manager API v2 documentation.
    Face Crop Use this syntax:

    <ImageURL>?im=FaceCrop

    For example:

    https://www.example.com/image.jpg?im=FaceCrop
    Use this syntax to apply the deep neural network algorithm:

    <ImageURL>?im=FaceCrop,algorithm=<alogorithm_type>

    For example:

    https://www.example.com/image.jpg?im=FaceCrop,algorithm=dnn

    For a complete list of transformation options see the FaceCrop section in the Image Manager API v2 documentation.
    Feature Crop Use this syntax:

    <ImageURL>?im=FeatureCrop,width=<width>,height=<height>

    For example:

    https://www.example.com/image.jpg?im=FeatureCrop,width=500,height=200
    Use this syntax to apply Feature Crop using a shortcut:

    <ImageURL>?im=FeatureCrop, size=(<width>,<height>)

    For example:

    https://www.example.com/image.jpg?im=FeatureCrop,size=(500,200)

    For a complete list of transformation options see the FeatureCrop section in the Image Manager API v2 documentation.
    Fit and Fill Use this syntax:

    <ImageURL>?im=FitAndFill,width=<resized_width>,height<resized_height>

    For example:

    https://www.example.com/image.jpg?im=FitAndFill,width=400,height=500
    Use this syntax to apply FitAndFill using a shortcut:

    <ImageURL>?im=FitAndFill=(<resized_width>,<resized_height>)

    For example:

    https://www.example.com/image.jpg?im=FitAndFill=(400,500)

    For a complete list of transformation options see the FitAndFill section in the Image Manager API v2 documentation.
    Goop Use this syntax:

    <ImageURL>?im=Goop

    For example:

    https://www.example.com/image.jpg?im=Goop

    For a complete list of transformation options see the Goop section in the Image Manager API v2 documentation.
    Grayscale Use this syntax:

    <ImageURL>?im=Grayscale

    For example:

    https://www.example.com/image.jpg?im=Grayscale

    For a complete list of transformation options see the Grayscale section in the Image Manager API v2 documentation.
    Hue/Saturation/Lightness Use this syntax:

    <ImageURL>?im=HSL,hue=<hue_value>,saturation=<saturation_value>,lightness=<lightness_value>

    For example:

    https://www.example.com/image.jpg?im=HSL,hue=1,saturation=1.5,lightness=1.5

    For a complete list of transformation options see the HLS section in the Image Manager API v2 documentation.
    Hue/Saturation/Value Use this syntax:

    <ImageURL>?im=HSV,hue=<hue_value>,saturation=<saturation_value>,value<lightness_or_darkness_value>

    For example:

    https://www.example.com/image.jpg?im=HSV,hue=0.5,saturation=2,value=1

    For a complete list of transformation options see the HSV section in the Image Manager API v2 documentation.
    Max Colors Use this syntax:

    <ImageURL>?im=Maxcolors,colors=<number_of_colors>

    For example:

    https://www.example.com/image.jpg?im=MaxColors,colors=35

    For a complete list of transformation options see the Max Colors section in the Image Manager API v2 documentation.
    Mirror Use this syntax:

    <ImageURL>?im=Mirror,horizontal

    For example:

    https://www.example.com/image.jpg?im=Mirror,horizontal

    For a complete list of transformation options see the Mirror section in the Image Manager API v2 documentation.
    Opacity Use this syntax:

    <ImageURL>?im=Opacity=<value>

    For example:

    https://www.example.com/image.jpg?im=Opacity=0.5

    For a complete list of transformation options see the Opacity section in the Image Manager API v2 documentation.
    Region of Interest Crop Use this syntax:

    <ImageURL>?im=RegionOfInterestCrop,width=<value>,height=<value>,regionOfInterest=width=<value>,height=<value>

    For example:

    https://www.example.com/image.jpg?im=RegionOfInterestCrop,width=400,height=300,regionOfInterest=(150,200)
    Use this syntax to apply RegionOfInterestCrop using a shortcut:

    <ImageURL>?im=RegionOfInterestCrop=(width>,<height>),regionOfInterest=(width>,<height>)

    For example:

    https://www.example.com/image.jpg?im=RegionOfInterestCrop=(400,300),regionOfInterest=(150,200)

    For a complete list of transformation options see the RegionOfInterestCrop section in the Image Manager API v2 documentation.
    Relative Crop Use this syntax:

    <ImageURL>?im=RelativeCrop,north=<value>,south=<value>

    For example:

    https://www.example.com/image.jpg?im=RelativeCrop,north=10,south=10

    For a complete list of transformation options see the RelativeCrop section in the Image Manager API v2 documentation.
    Resize Use this syntax:

    <ImageURL>?im=Resize,width=<resized_width>,height=<resized height>

    For example:

    https://www.example.com/image.jpg?im=Resize,width=250,height=125
    Use this syntax to apply the Resize transformation using a shortcut:

    <ImageURL>?im=Resize=(<resized_width>,<resized height>)

    For example:

    https://www.example.com/image.jpg?im=Resize=(250,125)

    For a complete list of transformation options see the Resize section in the Image Manager API v2 documentation.
    Rotate Use this syntax:

    <ImageURL>?im=Rotate,degrees=<number_of_degrees>

    For example:

    https://www.example.com/image.jpg?im=Rotate,degrees=13

    For a complete list of transformation options see the Rotate section in the Image Manager API v2 documentation.
    Scale Use this syntax:

    <ImageURL>?im=Scale,width=<width>,height=<height>

    For example:

    https://www.example.com/image.jpg?im=Scale,width=0.5,height=0.5

    For a complete list of transformation options see the Scale section in the Image Manager API v2 documentation.
    Shear Use this syntax:

    <ImageURL>?im=Shear,xShear=<xShear_value>,yShear=<yShear_value>

    For example:

    https://www.example.com/image.jpg?im=Shear,xShear=0.1,yShear=0.1

    For a complete list of transformation options see the Shear section in the Image Manager API v2 documentation.
    Trim Use this syntax:

    <ImageURL>?im=Trim,fuzz=<fuzz_value>,padding=<padding_value>

    For example:

    https://www.example.com/image.jpg?im=Trim,fuzz=0.5,padding=20

    For a complete list of transformation options see the Trim section in the Image Manager API v2 documentation.
    Unsharp Mask Use this syntax:

    <ImageURL>?im=UnsharpMask,gain=<value>,threshold=<value>

    For example:

    https://www.example.com/image.jpg?im=UnsharpMask,gain=2.0,threshold=0.08

    For a complete list of transformation options see the UnsharpMask section in the Image Manager API v2 documentation.