Remove Background

POST 
/v1/remove-background

Removes the background from an image and optionally adds AI-generated shadows, crops to the subject, and applies margins. When AI shadows are requested, an additional 3 credits will be consumed.

Input Image Limits:

• Max size: 25MB
• Min resolution: 64x64px
• Max resolution: 6000x6000px

Request

Header Parameters

Accept string

Acceptable response media type(s). application/json or image/*. Default is application/json.

application/json

Body

image_url urlrequired

URL of the image to be processed.

format string

Possible values: [png]

The format of the resultant image. Currently, only png is supported.

shadow

ShadowParameter

Enable and configure AI-generated shadow. When enabled, +3 credits are consumed. Pass true for automatic shadow estimation or provide a light source for custom control.

enabled booleanrequired

Enable AI shadow rendering.

opacity float

Possible values: <= 1

Default value: 0.5

Final composited shadow opacity (0–1).

light_source

object

Virtual light used to synthesize the shadow. x/y are normalized to image center (-1..1); z is height above subject (0..2).

size floatrequired

Possible values: <= 1

Default value: 0.3

Apparent emitter size/softness. Higher = softer penumbra.

position

object

required

x floatrequired

Possible values: >= -1 and <= 1

Default value: -0.3

y floatrequired

Possible values: >= -1 and <= 1

Default value: -0.6

z floatrequired

Possible values: <= 2

Default value: 0.7

crop CropParameter (boolean)

When true, crops the image to the region of interest (the detected subject).

margin MarginParameter (string)

(Beta) General margin applied to all sides when crop is enabled. Only applies if crop is true. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_left DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_right DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_top DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_bottom DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

multipart/form-data

Body

image_url url

URL of the image to be processed.

image binary

Binary file of the image to be processed, this is mutually exclusive with image_url, if both are provided the image will be used.

format string

Possible values: [png]

The format of the resultant image. Currently, only png is supported.

shadow

ShadowParameter

Enable and configure AI-generated shadow. When enabled, +3 credits are consumed. Pass true for automatic shadow estimation or provide a light source for custom control.

enabled booleanrequired

Enable AI shadow rendering.

opacity float

Possible values: <= 1

Default value: 0.5

Final composited shadow opacity (0–1).

light_source

object

Virtual light used to synthesize the shadow. x/y are normalized to image center (-1..1); z is height above subject (0..2).

size floatrequired

Possible values: <= 1

Default value: 0.3

Apparent emitter size/softness. Higher = softer penumbra.

position

object

required

x floatrequired

Possible values: >= -1 and <= 1

Default value: -0.3

y floatrequired

Possible values: >= -1 and <= 1

Default value: -0.6

z floatrequired

Possible values: <= 2

Default value: 0.7

crop CropParameter (boolean)

When true, crops the image to the region of interest (the detected subject).

margin MarginParameter (string)

(Beta) General margin applied to all sides when crop is enabled. Only applies if crop is true. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_left DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_right DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_top DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

margin_bottom DirectionalMarginParameter (string)

(Beta) Directional margin override that applies when crop is enabled. Only applies if crop is true. When specified, this overrides the general margin parameter for this specific side. When specified as a string with '%' (0-49%), it represents a percentage of the image dimensions. When specified as a string with 'px', it represents pixels (>=0px).

Responses

200

Success

application/json

Schema

Schema

result_url string

A URL to access the resultant image which is valid for 1 hour. File format will be png.

Example (from schema)

{
  "result_url": "https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.png"
}

image/*

Schema

Schema

image

Resultant image in binary format. The file format will be png.

400

The input could not be processed, often returned when the input image exceeds API limits.

application/json

Schema

Schema

error string

A description of the error.

error_code string
Possible values: [invalid_request_body, missing_parameter, invalid_parameter, unsupported_content_type, malformed_image, unsupported_image_format, file_size_too_large, resolution_too_high, unknown_foreground]
The error codes provide a way to programmatically handle errors.
The following error codes are currently in use:
• invalid_request_body: The request body was empty or invalid.
• missing_parameter: A required parameter was not provided.
• invalid_parameter: A parameter was provided but it was invalid.
• unsupported_content_type: The content type of the request was not application/json or multipart/form-data.
• malformed_image: The image could not be decoded.
• unsupported_image_format: The image format is not supported.
• file_size_too_large: The image file size is too large.
• resolution_too_high: The image resolution is too high.
• unknown_foreground: The foreground subject of the image could not be detected.

Example (from schema)

{
  "error": "File size too large",
  "error_code": "file_size_too_large"
}

401

The authentication token is missing or invalid.

application/json

Schema

Schema

error string
error_code string

Possible values: [invalid_auth_token]

Example (from schema)

{
  "error": "API Token not found",
  "error_code": "invalid_auth_token"
}

403

Returned when you have insufficient credits to perform the requested action.

application/json

Schema

Schema

error string
error_code string

Possible values: [insufficient_api_credits]

Example (from schema)

{
  "error": "Insufficient credits available",
  "error_code": "insufficient_api_credits"
}

429

Rate limit exceeded

application/json

Schema

Schema

error string
error_code string

Possible values: [rate_limit_exceeded]

Example (from schema)

{
  "error": "Too many requests",
  "error_code": "rate_limit_exceeded"
}

500

Internal service error

Loading...