▣ FILE MANIPULATION · IMAGE PROCESSING

Crop Images API

Hosted on ApyHub

What it does

The image crop API trims raster images to the frame you need. Send a public image URL or upload the file (up to 100 MB per request), and get the cropped image back as a file download or as a time-limited signed URL. It supports JPEG, PNG, WebP, GIF, TIFF and BMP.

There are two ways to define the crop. In dimension mode, set width and height to cut a box of that size from the top-left corner. In margin mode, set top, bottom, left and right insets in pixels (10px) or percent (5%) to trim each edge. Percent insets work well when a batch holds images of different sizes. Set preserve_format to true to keep the original format.

Use the image crop API to cut product shots to a consistent frame, trim toolbars and borders from screenshots, remove letterboxing from video stills, and prepare banner and social assets at fixed sizes. Profile photo uploads can be cropped server-side so every avatar matches your layout.

When the subject isn't in a predictable place, the Smart Crop API crops around detected faces instead. To fit a crop into exact display dimensions, follow it with the Image Resize API, then reduce file size with the Image Compression API.

▣ ENDPOINT 01 / 04

POST

Crop image (fetch by URL, return signed URL)

https://api.eu.apyhub.com/apyhub/crop-image/url/link

QUICKSTART

GUIDE

Quickstart

Crop an image from a URL using the dimension mode, with the image URL in the JSON body and the crop size in query parameters.

curl -X POST "https://api.eu.apyhub.com/apyhub/crop-image/url/link?width=400&height=300&output=cropped-result" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://assets.apyhub.com/samples/sample.png"}'

What you'll get back

Returns a JSON object with a data string field containing a time-limited pre-signed URL to the cropped image.

{
  "data": "https://storage.example.com/crop/cropped-result.png?X-Amz-Signature=def456&X-Amz-Expires=3600"
}

TRY ITLIVE · 30 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

body*

Request body for URL-mode crop endpoints. Send as application/json. Choose exactly one mode: Dimension mode — set url to the image to fetch; supply width and height as query parameters (both required, positive integers). The top/bottom/left/right fields are ignored in this mode. Margin mode — set image_url to the image to fetch; provide top, bottom, left, and right in the body as strings (NNpx or NN%). All four margin fields are required together. Query width/height are not used in this mode.

top

Top edge inset — e.g. 10px or 10%. Required with the other three margin fields in margin mode.

url

Image URL for dimension mode. Set this field to use width×height box crop from the top-left origin. Do not combine with image_url.

left

Left edge inset — e.g. 5px or 5%. Required with the other three margin fields in margin mode.

About this endpoint

What it does

Crops an image fetched from a URL and returns a signed URL for the cropped result. Use either dimension mode with url plus width and height, or margin mode with image_url plus top, bottom, left, and right.

Query Parameter(s)

Attribute	Type	Description
width	Integer	Positive integer. Used in dimension mode to define the crop box width from the top-left origin.
height	Integer	Positive integer. Used in dimension mode to define the crop box height from the top-left origin.
output	String	Output filename base.
preserve_format	Boolean	Default: `false`. Preserves the source image format when set.

Request Body

Parameter	Type	Description
top	String	Top edge inset for margin mode. Use a string such as `10px` or `10%`.
url	String	Image URL for dimension mode. Use this to crop by width and height. Do not combine with `image_url`.
left	String	Left edge inset for margin mode. Use a string such as `5px` or `5%`.
right	String	Right edge inset for margin mode. Use a string such as `5px` or `5%`.
bottom	String	Bottom edge inset for margin mode. Use a string such as `10px` or `10%`.
image_url	String	Image URL for margin mode. Use this with the four inset fields. Do not combine with `url`.

Response

Returns a JSON object with a data string field — a time-limited pre-signed URL to the stored cropped image. The response schema declares this field as always present on a successful response.

Parameter	Type	Description
data	String	Time-limited pre-signed URL to the stored cropped image. Always present on a 200 response.

▣ ENDPOINT 02 / 04

POST

Crop image (multipart upload, download file)

https://api.eu.apyhub.com/apyhub/crop-image/multi-part/download

QUICKSTART

GUIDE

Quickstart

Crop an uploaded image and return the cropped file.

curl -X POST "https://api.eu.apyhub.com/apyhub/crop-image/multi-part/download" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/sample.png"

What you'll get back

Returns a binary file response (string with format: binary), not a JSON object.

<cropped image bytes>

TRY ITLIVE · 30 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Crops an uploaded image and returns the resulting file as binary data. You can crop by providing width and height, or by specifying edge insets with top, right, bottom, and left.

Query Parameter(s)

Attribute	Type	Description
width	Integer	Output crop width. Minimum `1`.
height	Integer	Output crop height. Minimum `1`.
output	String	Output file name hint.
preserve_format	Boolean	Whether to preserve the original file format. Default: `false`.

Request Body

Parameter	Type	Description
image	Binary	Raster image file to crop. Binary upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP.
top	String	Top edge inset, such as `20px` or `10%`. Required together with `bottom`, `left`, and `right` for margin mode; omit all four to use dimension mode instead.
right	String	Right edge inset, such as `15px` or `5%`. See `top`.
bottom	String	Bottom edge inset, such as `20px` or `10%`. See `top`.
left	String	Left edge inset, such as `15px` or `5%`. See `top`.

Response

Returns a binary file containing the cropped image. The success response is a single binary string value, not a JSON object.

Notes

If you use margin mode, all four inset fields (top, right, bottom, and left) are expected together; if you use dimension mode, width and height define the crop size instead.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 03 / 04

POST

Crop image (multipart upload, return signed URL)

https://api.eu.apyhub.com/apyhub/crop-image/multi-part/link

QUICKSTART

GUIDE

Quickstart

Crop an image from a public link by sending the image URL along with the required crop file field.

curl -X POST "https://api.eu.apyhub.com/apyhub/crop-image/multi-part/link?width=400&height=300&output=cropped-result&preserve_format=true" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/sample.png"

What you'll get back

Returns a JSON object with a data string field containing a time-limited pre-signed URL to the cropped image.

{
  "data": "https://storage.example.com/crop/cropped-result.png?X-Amz-Signature=abc123&X-Amz-Expires=3600"
}

TRY ITLIVE · 30 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Crops an uploaded raster image and returns a time-limited pre-signed URL to the stored cropped image. The crop can be controlled by pixel/percentage insets (top, left, right, bottom) and/or by output dimensions via query parameters.

Query Parameter(s)

Attribute	Type	Description
width	Integer	Target crop width. Minimum: `1`.
height	Integer	Target crop height. Minimum: `1`.
output	String	Output name used for the returned asset.
preserve_format	Boolean	Preserve the input image format. Default: `false`.

Request Body

Parameter	Type	Description
image	Binary	Raster image file to crop. Binary upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP.
top	String	Top edge inset, such as `20px` or `10%`.
left	String	Left edge inset, such as `15px` or `5%`.
right	String	Right edge inset, such as `15px` or `5%`.
bottom	String	Bottom edge inset, such as `20px` or `10%`.

Response

Returns a JSON object with a data string field containing a URI. On a 200 response, data is always present and holds a time-limited pre-signed URL to the cropped image.

Parameter	Type	Description
data	String	Time-limited pre-signed URL to the stored cropped image. Always present on a `200` response.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 04 / 04

POST

Crop image (fetch by URL, download file)

https://api.eu.apyhub.com/apyhub/crop-image/url/download

QUICKSTART

GUIDE

Quickstart

Crop an image from a URL by sending the source image plus the required width and height query parameters.

curl -X POST "https://api.eu.apyhub.com/apyhub/crop-image/url/download?width=400&height=300" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://assets.apyhub.com/samples/sample.png"}'

What you'll get back

Returns the cropped image as binary data.

TRY ITLIVE · 30 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

body*

top

Top edge inset — e.g. 10px or 10%. Required with the other three margin fields in margin mode.

url

Image URL for dimension mode. Set this field to use width×height box crop from the top-left origin. Do not combine with image_url.

left

Left edge inset — e.g. 5px or 5%. Required with the other three margin fields in margin mode.

About this endpoint

What it does

Crops an image fetched from a URL and returns the resulting file as binary data. The request supports two modes: dimension-based cropping with url plus width and height, or margin-based cropping with image_url plus top, bottom, left, and right.

Query Parameter(s)

Attribute	Type	Description
width	Integer	Required in dimension mode. Positive integer; minimum `1`.
height	Integer	Required in dimension mode. Positive integer; minimum `1`.
output	String	Output filename/base name.
preserve_format	Boolean	Default: `false`.

Request Body

Parameter	Type	Description
top	String	Top edge inset for margin mode. Use a string such as `NNpx` or `NN%`. Required together with `bottom`, `left`, and `right`. Ignored in dimension mode.
url	String	Image URL for dimension mode. Must be a URI. Use this to crop a fetched image by `width` × `height` from the top-left origin. Do not combine with `image_url`.
left	String	Left edge inset for margin mode. Use a string such as `NNpx` or `NN%`. Required together with `top`, `bottom`, and `right`. Ignored in dimension mode.
right	String	Right edge inset for margin mode. Use a string such as `NNpx` or `NN%`. Required together with `top`, `bottom`, and `left`. Ignored in dimension mode.
bottom	String	Bottom edge inset for margin mode. Use a string such as `NNpx` or `NN%`. Required together with `top`, `left`, and `right`. Ignored in dimension mode.
image_url	String	Image URL for margin mode. Must be a URI. Use this to crop by edge insets with `top`, `bottom`, `left`, and `right`. Do not combine with `url`.

Response

Returns a binary file containing the cropped image. The output schema is a binary string, so the success response is file content rather than a JSON object.

Parameter	Type	Description
binary	String	Cropped image file content returned as binary data.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLCompress Images APIApyHub CALLCrop image around faces APIDosvak LLC CALLRemove Background from Images APIApyHub CALLImage Resize API: Resize Images to Exact DimensionsApyHub

From the blog

Reads that touch this API.

Video Thumbnails for SEO: How They Lift CTR, and How to Generate Them with an APISep 22, 2026 Generating Video Thumbnails with ApyHub’s API (Go Guide)Aug 7, 2026 Generating Thumbnails from Videos : A step-by-step guide in NodeJSJul 9, 2026 Exploring the Top Video Thumbnail ( Preview) APIsJul 9, 2026