> ## Documentation Index
> Fetch the complete documentation index at: https://pixelcut.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
## OpenAPI
````yaml POST /v1/remove-background
openapi: 3.1.0
info:
description: >-
The Pixelcut API specification, learn more about the API at at
https://www.pixelcut.ai/docs
version: 0.0.2
title: Pixelcut API
termsOfService: >-
https://pixelcut.notion.site/Pixelcut-API-Terms-of-Service-11b3b550490080d89a91e943d010efdf
contact:
name: API Support
email: api@pixelcut.ai
servers:
- url: https://api.developer.pixelcut.ai
description: Pixelcut API server
security: []
paths:
/v1/remove-background:
post:
tags:
- Endpoints
summary: Remove Background
description: >
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
operationId: remove-background
parameters:
- in: header
name: Accept
required: false
schema:
type: string
description: >-
Acceptable response media type(s). `application/json` or `image/*`.
Default is `application/json`.
requestBody:
content:
application/json:
schema:
type: object
required:
- image_url
properties:
image_url:
$ref: '#/components/schemas/ImageURLParameter'
format:
$ref: '#/components/schemas/ImageFormatParameter'
shadow:
$ref: '#/components/schemas/ShadowParameter'
crop:
$ref: '#/components/schemas/CropParameter'
margin:
$ref: '#/components/schemas/MarginParameter'
margin_left:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_right:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_top:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_bottom:
$ref: '#/components/schemas/DirectionalMarginParameter'
multipart/form-data:
schema:
type: object
properties:
image_url:
$ref: '#/components/schemas/ImageURLParameter'
image:
$ref: '#/components/schemas/BinaryImageParameter'
format:
$ref: '#/components/schemas/ImageFormatParameter'
shadow:
$ref: '#/components/schemas/ShadowParameter'
crop:
$ref: '#/components/schemas/CropParameter'
margin:
$ref: '#/components/schemas/MarginParameter'
margin_left:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_right:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_top:
$ref: '#/components/schemas/DirectionalMarginParameter'
margin_bottom:
$ref: '#/components/schemas/DirectionalMarginParameter'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PngImageJSONResponse'
image/*:
schema:
$ref: '#/components/schemas/PngBinaryResponse'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
security:
- ApiKeyAuth: []
components:
schemas:
ImageURLParameter:
type: string
format: url
description: URL of the image to be processed.
example: https://cdn3.pixelcut.app/product.jpg
ImageFormatParameter:
type: string
format: string
enum:
- png
description: The format of the resultant image. Currently, only png is supported.
ShadowParameter:
description: >
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.
properties:
enabled:
type: boolean
default: false
description: Enable AI shadow rendering.
opacity:
type: number
format: float
minimum: 0
maximum: 1
default: 0.5
description: Final composited shadow opacity (0–1).
light_source:
$ref: '#/components/schemas/ShadowLightSource'
required:
- enabled
CropParameter:
type: boolean
description: >
When true, crops the image to the region of interest (the detected
subject).
default: false
MarginParameter:
type: string
description: >
(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).
example: 100px
DirectionalMarginParameter:
type: string
description: >
(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).
example: 50px
BinaryImageParameter:
type: string
format: binary
description: >-
Binary file of the image to be processed, this is mutually exclusive
with image_url, if both are provided the image will be used.
PngImageJSONResponse:
type: object
properties:
result_url:
type: string
description: >-
A URL to access the resultant image which is valid for 1 hour. File
format will be png.
example: >-
https://assets.pixelcut.app/public/result/a16646be-91c8-4e3a-b359.png
PngBinaryResponse:
type: string
format: binary
properties:
image:
description: Resultant image in binary format. The file format will be png.
ShadowLightSource:
type: object
description: >
Virtual light used to synthesize the shadow. x/y are normalized to image
center (-1..1); z is height above subject (0..2).
properties:
size:
type: number
format: float
minimum: 0
maximum: 1
default: 0.3
description: Apparent emitter size/softness. Higher = softer penumbra.
position:
type: object
properties:
x:
type: number
format: float
minimum: -1
maximum: 1
default: -0.3
'y':
type: number
format: float
minimum: -1
maximum: 1
default: -0.6
z:
type: number
format: float
minimum: 0
maximum: 2
default: 0.7
required:
- x
- 'y'
- z
required:
- size
- position
responses:
Error400:
description: >-
The input could not be processed, often returned when the input image
exceeds API limits.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: A description of the error.
example: File size too large
error_code:
type: string
enum:
- invalid_request_body
- missing_parameter
- invalid_parameter
- unsupported_content_type
- malformed_image
- unsupported_image_format
- file_size_too_large
- resolution_too_high
- unknown_foreground
example: file_size_too_large
description: >
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.
Error401:
description: The authentication token is missing or invalid.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: API Token not found
error_code:
type: string
enum:
- invalid_auth_token
Error403:
description: >-
Returned when you have insufficient credits to perform the requested
action.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Insufficient credits available
error_code:
type: string
enum:
- insufficient_api_credits
Error429:
description: Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Too many requests
error_code:
type: string
enum:
- rate_limit_exceeded
Error500:
description: Internal service error
securitySchemes:
ApiKeyAuth:
description: >
All API requests require a valid api key. Include your token as a HTTP
request header in the following format: `X-API-Key: skXXXXXXXXXXXXXXXX`.
You can obtain an api key by signing up for developer access in your
Pixelcut account.
type: apiKey
name: X-API-KEY
in: header
````