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:

between_eyes_and_nose - Crop from between eyes and nose to feet.

between_nose_and_mouth - Crop from between node and mouth to feet.

face - Crop from under the face to feet and below.

eyes - Crop from eyes to feet and below.

nose - Crop from nose to feet and below.

mouth - Crop from mouth to feet and below.

📌

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:

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.

bottom - This margin dictates how much to shift upward from the bottom of the image towards the marker.

left - The left margin specifies the percentage to shift leftward from the center of the image.

right Similarly, the right margin denotes the percentage to shift rightward from the center of the image.

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]+)$

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

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://us1-api.crop.photo/v1/crop/unrecognizable-crop' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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
    }
}'

Responses

🟢200Success

application/octet-stream

Body

jobs

array [object {3}]

required

An array of job objects, each representing the status of a specific job or jobs associated with specified tags.

job_id

string

required

The unique identifier for the job.

status

enum<string>

required

The current status of the job.

Allowed values:

pendingprocessingcompletedfailed

job_labels

array[string]

required

An array of associated job_labels to this job.

results

array [object {2}]

required

output_image_url

string

required

The URL to the output image, available only if the job is completed successfully.

crop_coordinates

object

required

error_message

string

required

An error message, provided if the job has failed.

🟠401Unauthorized

🟠400Invalid Input | Crop.photo

🟢200Image Crop Response JSON

Modified at 2024-04-26 16:38:17

Body Aware Crop

Remove Background