▣ FILE MANIPULATION · IMAGE PROCESSING

Crop Images API

Hosted on ApyHub

What it does

Image Cropper trims raster images by URL or file upload and returns either a downloaded crop or a time-limited signed URL to the result. Use it when you need to cut product shots, profile images, screenshots, or banner assets down to a specific frame without handling image processing yourself.

Send an image URL with width and height for a box crop from the top-left origin, or send an image_url/image with top, bottom, left, and right margin values to crop by insets. Margin values are strings such as 10px or 5%, and the service accepts preserve_format plus an output name on the upload endpoints. For URL-based crops, you can choose whether you want the cropped file returned directly or a pre-signed download link in the response.

The response is intentionally simple: download-mode endpoints return binary image data, while link-mode endpoints return a data field containing a signed URL. That makes Image Cropper easy to slot into workflows that resize CMS assets, generate thumbnails, or prepare images for listings and moderation queues.

If you already store images remotely, crop by URL. If you receive uploads from users, send the file directly and get back the cropped image in the format you need.

▣ ENDPOINT 01 / 04

POST

Crop image (fetch by URL, return signed URL)

http://localhost:8080/apyhub/crop-image/url/link

QUICKSTARTGUIDE

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 "http://localhost:8080/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.

right

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

bottom

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

image_url

Image URL for margin mode. Set this field to use edge-inset cropping with `top`, `bottom`, `left`, and `right`. Do not combine with `url`.

width

height

output

preserve_format

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	Mandatory	Description
width	Integer	Yes (if `url` is used)	Positive integer. Used in dimension mode to define the crop box width from the top-left origin.
height	Integer	Yes (if `url` is used)	Positive integer. Used in dimension mode to define the crop box height from the top-left origin.
output	String	No	Output filename base.
preserve_format	Boolean	No	Default: `false`. Preserves the source image format when set.

Request Body

Parameter	Type	Mandatory	Description
top	String	Yes (if `image_url` is used)	Top edge inset for margin mode. Use a string such as `10px` or `10%`.
url	String	Yes (if `width` and `height` are used)	Image URL for dimension mode. Use this to crop by width and height. Do not combine with `image_url`.
left	String	Yes (if `image_url` is used)	Left edge inset for margin mode. Use a string such as `5px` or `5%`.
right	String	Yes (if `image_url` is used)	Right edge inset for margin mode. Use a string such as `5px` or `5%`.
bottom	String	Yes (if `image_url` is used)	Bottom edge inset for margin mode. Use a string such as `10px` or `10%`.
image_url	String	Yes (if `top`, `bottom`, `left`, and `right` are used)	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	Mandatory	Description
data	String	Yes	Time-limited pre-signed URL to the stored cropped image. Always present on a 200 response.

Query parameters

Name

Type

Description

widthOPTIONAL

integer

—

heightOPTIONAL

integer

—

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

▣ ENDPOINT 02 / 04

POST

Crop image (multipart upload, download file)

http://localhost:8080/apyhub/crop-image/multi-part/download

QUICKSTARTGUIDE

Quickstart

Crop an uploaded image and return the cropped file.

curl -X POST "http://localhost:8080/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	Mandatory	Description
width	Integer	No	Output crop width. Minimum `1`.
height	Integer	No	Output crop height. Minimum `1`.
output	String	No	Output file name hint.
preserve_format	Boolean	No	Whether to preserve the original file format. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	Raster image file to crop. Binary upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP.
top	String	No	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	No	Right edge inset, such as `15px` or `5%`. See `top`.
bottom	String	No	Bottom edge inset, such as `20px` or `10%`. See `top`.
left	String	No	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.

Query parameters

Name

Type

Description

widthOPTIONAL

integer

—

heightOPTIONAL

integer

—

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

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)

http://localhost:8080/apyhub/crop-image/multi-part/link

QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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	Mandatory	Description
width	Integer	No	Target crop width. Minimum: `1`.
height	Integer	No	Target crop height. Minimum: `1`.
output	String	No	Output name used for the returned asset.
preserve_format	Boolean	No	Preserve the input image format. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	Raster image file to crop. Binary upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP.
top	String	No	Top edge inset, such as `20px` or `10%`.
left	String	No	Left edge inset, such as `15px` or `5%`.
right	String	No	Right edge inset, such as `15px` or `5%`.
bottom	String	No	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	Mandatory	Description
data	String	Yes	Time-limited pre-signed URL to the stored cropped image. Always present on a `200` response.

Query parameters

Name

Type

Description

widthOPTIONAL

integer

—

heightOPTIONAL

integer

—

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

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)

http://localhost:8080/apyhub/crop-image/url/download

QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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.

right

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

bottom

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

image_url

Image URL for margin mode. Set this field to use edge-inset cropping with `top`, `bottom`, `left`, and `right`. Do not combine with `url`.

width

height

output

preserve_format

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	Mandatory	Description
width	Integer	Yes	Required in dimension mode. Positive integer; minimum `1`.
height	Integer	Yes	Required in dimension mode. Positive integer; minimum `1`.
output	String	No	Output filename/base name.
preserve_format	Boolean	No	Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
top	String	Yes (if margin mode)	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	Yes (if dimension mode)	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	Yes (if margin mode)	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	Yes (if margin mode)	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	Yes (if margin mode)	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	Yes (if margin mode)	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	Mandatory	Description
binary	String	Yes	Cropped image file content returned as binary data.

Query parameters

Name

Type

Description

widthOPTIONAL

integer

—

heightOPTIONAL

integer

—

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

▣ 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.