Crop.photo
  1. Crop.photo API
Crop.photo
  • Crop.photo API
    • Introduction
    • Authentication
    • FAQs
    • Examples
    • Interactive API Testing
    • Auto Resize & Align
      POST
    • Body Aware Crop
      POST
    • Unrecognizable Crop
      POST
    • Remove Background
      POST
    • Create Banner Job
      POST
    • AI Lifestyle Crop
      POST
    • Banners Job Status
      POST
  1. Crop.photo API

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 - 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:
0
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:
0
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:
8
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
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
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
Previous
Interactive API Testing
Next
Body Aware Crop
Built with