Body Aware Crop

POST

/crop/body-aware-crop

The Body-Aware Crop feature in Crop.photo API enables precise and versatile cropping based on various body markers, catering to diverse use cases and enhancing image customization. These markers facilitate targeted cropping to specific body areas, allowing users to focus on particular features or aspects of the subject in the image.

Supported Cropping Markers:

FACE: Focuses strictly on the face area.

HEAD: Includes the entire head.

HEAD_TO_KNEES: Crops from the head down to the knees.

HEAD_TO_ELBOWS: Crops from the head to the elbows.

HIPS: Focuses around the hip and waist area.

HEAD_TO_SHOULDER: Includes the head and shoulder area.

PERSON: Captures the entire body.

MID_HALF: Focuses on the middle half of the body. Typically from upper waist to thighs.

UPPER_HALF: Crops the upper half of the body from head to waist.

10.

LOWER_HALF: Targets the lower half of the body from waist to feet.

Each marker provides specific framing options, allowing users to tailor their cropping preferences for various applications such as fashion, identification, or social media usage. Whether it's highlighting facial features for a portrait or showcasing full-body attire for fashion purposes, the Body-Aware Crop feature offers flexibility and precision in image cropping.

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

margins

object

required

top

number

Top Margin

required

Defines the margin on the top side of the subject, specified as a percentage of the subject's size.

Minimum value: 0.

Maximum value: 100.

>= 0<= 100

bottom

number

Bottom Margin

required

Defines the margin on the bottom side of the subject, specified as a percentage of the subject's size.

Minimum value: 0.

Maximum value: 100.

>= 0<= 100

left

number

Left Margin

required

Specifies the margin on the left side of the subject, specified as a percentage of the subject's size.

Minimum value: 0.

Maximum value: 100.

>= 0<= 100

right

number

Right Margin

required

Controls the margin on the right side of the subject, specified as a percentage of the subject's size.

Minimum value: 0.

Maximum value: 100.

>= 0<= 100

center_around_face

boolean

optional

Focuses on centering the face horizontally in the output image for aesthetic appeal.

Default:

true

crop_marker

enum<string>

required

Choose crop marker

Allowed values:

personheadfacehead_to_shoulderupper_halfhead_to_kneeshipslower_halfhead_to_elbowsmid_half

Example:

head_to_shoulder

Example

{
  "image_url": "https://acme.s3.aws.com/image.png",
  "background": "white",
  "output_format": "auto",
  "output_dimension": "1080x1080",
  "response_type": "stream",
  "margins": {
    "top": 0,
    "bottom": 0,
    "left": 0,
    "right": 0
  },
  "center_around_face": "true",
  "crop_marker": "person"
}

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/body-aware-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",
    "margins": {
        "top": 0,
        "bottom": 0,
        "left": 0,
        "right": 0
    },
    "center_around_face": "true",
    "crop_marker": "person"
}'

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:13

Auto Resize & Align

Unrecognizable Crop