▣ FILE MANIPULATION · IMAGE PROCESSING

Image Cropper

What it does

Image Cropper lets you crop an image from a URL or an uploaded file and get back either the cropped binary file or a time-limited signed URL.

Use URL mode when the image is already hosted: send url for dimension mode, or image_url with top, bottom, left, and right for margin mode. In dimension mode, provide width and height as query parameters to crop a box from the top-left origin. In margin mode, the four edge insets are strings such as 10px or 5%.

Use multipart mode when you want to upload the source image directly. Send image as a binary file, then crop with the same dimension or margin patterns. Supported upload formats include JPEG, PNG, WebP, GIF, TIFF, and BMP.

The responses are simple: download endpoints return the cropped image as binary, while link endpoints return a JSON object with data, a pre-signed URL to the stored crop. Set preserve_format when you want to keep the original format, and use output to name the generated file.

▣ ENDPOINT 01 / 04

POST

Crop image (fetch by URL, download file)

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

QUICKSTART

GUIDE

Quickstart

Crop an image from a URL using the required width and height query parameters.

curl -X POST "https://api.eu.apyverse.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 (string with format: binary), not JSON.

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 the cropped file as binary data. The endpoint supports two mutually exclusive modes: dimension mode using url with width and height query parameters, or margin mode using image_url with top, bottom, left, and right body fields.

Query Parameter(s)

Attribute	Type	Mandatory	Description
width	Integer	Yes (if using `url` dimension mode)	Crop width in pixels. Minimum: `1`.
height	Integer	Yes (if using `url` dimension mode)	Crop height in pixels. Minimum: `1`.
output	String	No	Output name.
preserve_format	Boolean	No	Whether to preserve the original image format. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
top	String	Yes (if using `image_url` margin mode)	Top edge inset, such as `10px` or `10%`. Required together with `bottom`, `left`, and `right` in margin mode.
url	String	Yes (if using dimension mode)	Image URL to fetch for dimension-based cropping. Use with query parameters `width` and `height`. Do not combine with `image_url`. Format: URI.
left	String	Yes (if using `image_url` margin mode)	Left edge inset, such as `5px` or `5%`. Required together with `top`, `bottom`, and `right` in margin mode.
right	String	Yes (if using `image_url` margin mode)	Right edge inset, such as `5px` or `5%`. Required together with `top`, `bottom`, and `left` in margin mode.
bottom	String	Yes (if using `image_url` margin mode)	Bottom edge inset, such as `10px` or `10%`. Required together with `top`, `left`, and `right` in margin mode.
image_url	String	Yes (if using `image_url` margin mode)	Image URL to fetch for margin-based cropping. Use with `top`, `bottom`, `left`, and `right`. Do not combine with `url`. Format: URI.

Response

Returns a binary file containing the cropped image. The success response is a binary payload, not a JSON object, so there are no JSON fields to document.

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 (fetch by URL, return signed URL)

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

QUICKSTART

GUIDE

Quickstart

Crop an image from a URL by sending the source image plus the target size.

curl -X POST "https://api.eu.apyverse.com/apyhub/crop-image/url/link?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 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*

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 time-limited signed URL for the cropped result. The request supports two modes: dimension mode using url with width and height query parameters, or margin mode using image_url with top, bottom, left, and right in the request body.

Query Parameter(s)

Attribute	Type	Mandatory	Description
width	Integer	Yes (if `url` is used)	Image crop width in pixels. Minimum: `1`. Used in dimension mode.
height	Integer	Yes (if `url` is used)	Image crop height in pixels. Minimum: `1`. Used in dimension mode.
output	String	No	Output name for the cropped file.
preserve_format	Boolean	No	Whether to preserve the source image format. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes (if `width` and `height` are used)	Image URL for dimension mode. Format: URI. Set this field to use width × height box crop from the top-left origin. Do not combine with `image_url`.
image_url	String	Yes (if `top`, `bottom`, `left`, and `right` are used)	Image URL for margin mode. Format: URI. Set this field to use edge-inset cropping with `top`, `bottom`, `left`, and `right`. Do not combine with `url`.
top	String	Yes (if `image_url` is used)	Top edge inset, such as `10px` or `10%`. Required together with `bottom`, `left`, and `right` in margin mode.
bottom	String	Yes (if `image_url` is used)	Bottom edge inset, such as `10px` or `10%`. Required together with `top`, `left`, and `right` in margin mode.
left	String	Yes (if `image_url` is used)	Left edge inset, such as `5px` or `5%`. Required together with `top`, `bottom`, and `right` in margin mode.
right	String	Yes (if `image_url` is used)	Right edge inset, such as `5px` or `5%`. Required together with `top`, `bottom`, and `left` in margin mode.

Response

Returns a JSON object with a data string field containing a time-limited pre-signed URL for the stored cropped image. The data field is always present on a successful 200 response.

Parameter	Type	Mandatory	Description
data	String	Yes	Time-limited pre-signed URL to the stored cropped image. Format: URI. 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 03 / 04

POST

Crop image (multipart upload, download file)

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

QUICKSTART

GUIDE

Quickstart

Upload a single image to get a cropped file back. Replace sample.png with the image you want to crop.

curl -X POST "https://api.eu.apyverse.com/apyhub/crop-image/multi-part/download" \
  -H "apy-token: $APY_TOKEN" \
  -F "[email protected]"

What you'll get back

Returns a binary file (string with format: binary) containing the cropped image.

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 cropped file as a binary download. You can crop by specifying width and height, or by providing edge insets with top, right, bottom, and left.

Query Parameter(s)

Attribute	Type	Mandatory	Description
width	Integer	No	Crop width. Minimum `1`.
height	Integer	No	Crop height. Minimum `1`.
output	String	No	Output file name or base name.
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%`. 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 download, represented as a JSON schema value of type string with format: binary. The success response body is the cropped image file.

Parameter	Type	Mandatory	Description
value	String	Yes	Binary file content for the cropped image download.

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 (multipart upload, return signed URL)

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

QUICKSTART

GUIDE

Quickstart

Upload an image and get back a cropped image URL.

curl -X POST "https://api.eu.apyverse.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 for 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 image and returns a time-limited signed URL to the generated file. The crop can be constrained using width and height query parameters, and/or edge inset values in the request body.

Query Parameter(s)

Attribute	Type	Mandatory	Description
width	Integer	No	Crop width in pixels. Minimum: `1`.
height	Integer	No	Crop height in pixels. Minimum: `1`.
output	String	No	Output filename/base name for the generated cropped image.
preserve_format	Boolean	No	Whether to 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 time-limited pre-signed URL to the stored cropped image. The schema indicates this is always present on a successful 200 response.

Parameter	Type	Mandatory	Description
data	String	Yes	Time-limited pre-signed URL to the stored cropped image. This is a URI.

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.

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