Auto Resize & Align

POST

/crop/auto-resize-align

Auto resize and align in Crop.photo, seamlessly resize and align your products within the frame while replacing the background with given color or background image.
This feature guarantees a polished appearance for a diverse range of products, including shoes, beverages, and home decor, enhancing the overall visual presentation.
Maintaining a consistent eye level significantly improves the browsing experience across various aspect ratios on your online storefront. The Auto Resize & Align API ensures precise alignment and sizing of the focal object, typically a product.

Example 1:
To resize the input image to a 2000x3000 dimension and automatically align the product in the center with uniform 8% margins around it, use the API as follows:

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

image_url

string <url>

required

Specifies the URL of the image. The URL should be a direct link to the image file, allowing the system to retrieve and process the image as needed.

The URL must be publicly accessible to ensure the system can retrieve the image without authentication barriers.

Supported image formats include .png, .jpg, .jpeg and .webp, etc. Ensure the URL points directly to a compatible image file.

Use a reliable hosting service to prevent issues with image availability or loading times.

This property is essential for operations that require an image as input, facilitating the integration of external images into the workflow.

Example:

https://acme.s3.aws.com/image.png

background

string

required

Determines the background setting for the image. The options include:

transparent - Removes the background from the image, allowing for transparency. Note that only PNG and WebP file formats support transparent backgrounds. Ensure to specify one of these formats if you opt for a transparent background.

white - Sets the background color to white. This is the default setting, suitable for contexts where a neutral background is preferred.

{#hex_code} - Allows setting the background to any custom color by providing a hex color code. For example, #FF5733 for a vibrant orange background.

{image_url} - Uses an image as the background by specifying its URL. Ensure the URL is accessible and the image format is compatible with your requirements.

none - Keep original background. Note: this option is not supported in all the APIs. Please read the documentation and try the APIs before using them in productions.
Note: Please note that the option none is only supported in the body-parts API and not in the auto-resize-align API.

Default:

white

Examples:

transparentwhite#AAAAAAhttp://example.com/background.png

Match pattern:

^(transparent|white|#[0-9A-Fa-f]{6}|https?:\/\/[^\s]+)$

preserve_edge_contact

boolean

optional

Some subjects are attached to edges. Keep it or remove it to control alignment.

Default:

true

output_format

enum<string>

required

Pick the perfect image format for your cropped images based on your unique needs.

Allowed values:

autojpegpngwebp

Default:

auto

Example:

auto

output_dimension

string

Output Dimension

required

Possible values are:

match_to_original - Keep original image dimension.

trim_to_subject - Note: Only supported in the /crop/lifestyle API. Keep subject dimensions with all the given margins around it.

WidthxHeight - Resize the image to given width and height. Like 1600x1600

Example:

1080x1080

Match pattern:

^(match_to_original|trim_to_subject|(\d{1,4})x(\d{1,4}))$

response_type

enum<string>

required

Specifies the method by which the response is delivered to the client. Available options include:

stream - The response is streamed back in the same request. This option is optimal for immediate processing or display of the data without the need for a separate download step.

url - The response will be provided as a signed S3 URL. This method will be supported in the future and is ideal for cases where the response needs to be accessed multiple times or shared.

Note: Choosing the appropriate response type depends on the use case and the desired workflow for accessing the response data.

Allowed values:

streamurl

Default:

stream

Example:

stream

margins

object (Auto Resize and Align Minimum Margins)

optional

horizontal_alignment

enum<string>

optional

Specifies the horizontal alignment of the subject. Options are left, right, or center. By default, it is center.

Allowed values:

centerrightleft

Default:

center

Example:

center

horizontal_margin

integer

optional

Applicable only when horizontal_alignment is set to left or right. Specifies the margin as a percentage of the subject's size, controlling the distance from the subject to the selected side. Default value is 0%.

>= 0<= 49

Default:

vertical_alignment

enum<string>

optional

Specifies the vertical alignment of the subject. Options are top, bottom, or center. By default, or if this property is left empty, it is center.

Allowed values:

centertopbottom

Default:

center

Example:

center

vertical_margin

integer

optional

Applicable only when vertical_alignment is set to top or bottom. Specifies the margin as a percentage of the subject's size, controlling the distance from the subject to the selected side. Default value is 0%.

>= 0<= 49

Default:

minimum_margin

integer

Minimum Margin

required

Defines the minimum margin around the subject as a percentage of the subject's size. This margin is always applied to all sides, ensuring the subject is not too close to any edge. Applies even if other margins are set to 0%.

>= 1<= 49

Default:

Example

{
    "image_url": "https://acme.s3.aws.com/image.png",
    "background": "white",
    "preserve_edge_contact": "true",
    "output_format": "auto",
    "output_dimension": "1080x1080",
    "response_type": "stream",
    "margins": {
        "horizontal_alignment": "center",
        "horizontal_margin": 0,
        "vertical_alignment": "center",
        "vertical_margin": 0,
        "minimum_margin": 8
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://us1-api.crop.photo/v1/crop/auto-resize-align' \
--header 'Content-Type: application/json' \
--data-raw '{
    "image_url": "https://acme.s3.aws.com/image.png",
    "background": "white",
    "preserve_edge_contact": "true",
    "output_format": "auto",
    "output_dimension": "1080x1080",
    "response_type": "stream",
    "margins": {
        "horizontal_alignment": "center",
        "horizontal_margin": 0,
        "vertical_alignment": "center",
        "vertical_margin": 0,
        "minimum_margin": 8
    }
}'

Responses

🟢200Binary Octel Stream Response

application/octet-stream

Body

object {0}

🟢200Image Crop Response JSON

🟢200Success

🟠401Unauthorized

🟠400Invalid Input | Crop.photo

Modified at 2025-03-17 15:49:11

Interactive API Testing

Body Aware Crop