Crop.photo
  • Crop.photo API
    • Authentication
    • Common Exceptions
    • Examples
    • Auto Resize & AlignPOST
    • Body Aware CropPOST
    • Unrecognizable CropPOST
    • Remove BackgroundPOST
    • Create Banner JobPOST
    • AI Lifestyle CropPOST
    • Banners Job StatusPOST
logoPowered by Apidog
  1. Crop.photo API

Unrecognizable Crop

POST/crop/unrecognizable-crop

Unrecogniable crop is a specialized feature geared primarily towards the retail/wholesale and fashion industries. It purposefully crops out the faces of models to focus viewer attention on the products. This not only keeps the audience focused on the item but also eliminates the need to pay royalties to models or agencies when distributing the images across various wholesale channels like e-commerce marketplaces.

When to use Headless Crop?
E-commerce use-cases that need to crop the top portion of the face or a model's body in order to turn the model's image into an unrecognizable face.
You can find example and details here: https://help.crop.photo/en/articles/6720728-headless-face-crop.

Following markers are supported:

  1. between_eyes_and_nose - Crop from between eyes and nose to feet.
  2. between_nose_and_mouth - Crop from between node and mouth to feet.
  3. face - Crop from under the face to feet and below.
  4. eyes - Crop from eyes to feet and below.
  5. nose - Crop from nose to feet and below.
  6. mouth - Crop from mouth to feet and below.

:::highlight red 📌
When it comes to margins, the behavior in the unrecognizable crop differs from other APIs. For the best grasp of how margins function, experimenting with them in the Crop.photo application is recommended. Begin with a margin value of 100 in all fields and adjust as necessary.
:::

Understanding Margins:

  1. top - The top margin ranges from 0 to 100. This value indicates how many pixels to move downward, relative to the original image dimensions from the marker. For instance, if set to 10%, it shifts the cropping area downward by 10% of the image's height.
  2. bottom - This margin dictates how much to shift upward from the bottom of the image towards the marker.
  3. left - The left margin specifies the percentage to shift leftward from the center of the image.
  4. right Similarly, the right margin denotes the percentage to shift rightward from the center of the image.

Request

Authorization: Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example
Authorization: Bearer 2f68dbbf-519d-4f01-9636-e2421b68f379
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]+)$
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
crop_marker
enum<string> 
optional
Allowed values:
between_eyes_and_nosebetween_nose_and_mouth
Example:
between_eyes_and_nose
margins
object 
optional
top
number 
Top Margin
optional

This value indicates how much to shift downward, relative to the original image dimensions from the marker. For example, if set to 10%, it shifts the cropping area downward by 10% of the image's height.

>= 0<= 100
Default:
100
bottom
number 
Bottom Margin
optional

Specifies how much to shift upward from the bottom of the image towards the marker, relative to the image dimensions.

>= 0<= 100
Default:
100
left
number 
Left Margin
optional

Specifies the percentage to shift leftward from the center of the image relative to the image dimensions.

>= 0<= 100
Default:
100
right
number 
Right Margin
optional

Specifies the percentage to shift rightward from the center of the image relative to the image dimensions.

>= 0<= 100
Default:
100
Example
{
  "image_url": "https://acme.s3.aws.com/image.png",
  "background": "white",
  "output_format": "auto",
  "output_dimension": "1080x1080",
  "response_type": "stream",
  "crop_marker": "between_eyes_and_nose",
  "margins": {
    "top": 100,
    "bottom": 100,
    "left": 100,
    "right": 100
  }
}

Request samples

Responses

Success(200)
HTTP Code: 200
Content Type : Binaryapplication/octet-stream
Example
Not configured
Last modified: 9 months ago