> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crop Image

> Crop a media-library image into a new hosted image

Crops an image from your media library, or a Pexels or Unsplash photo, and
saves the result as a new image in the library. The crop is baked into the
file, so Gmail, Outlook and every other email client show exactly the area you
chose. A fixed `height` with `objectFit: "cover"` on an image block only crops
with CSS, which some clients ignore.

The original stays in the library. Use the returned `asset.url` as the image
block's `src` and store the returned `crop` object on the block as `crop`, so
the editor can re-open or undo the crop later. To change a crop, crop
`crop.sourceSrc` (the original) again rather than the cropped image.

Requests are idempotent: cropping the same source to the same pixel area
returns the same asset instead of adding a copy, so you can safely retry after
a timeout. A repeated crop keeps the first request's alt text. Requires the
`emails:write` scope.

To crop an image hosted somewhere else, upload it first with
[Create Image Upload URL](https://docs.sequenzy.com/api-reference/media/upload-url.md), then crop the
uploaded URL.

## Request

**sourceUrl** `string` *required*

Hosted URL of the original image: a media-library URL (for example from
[Complete Image Upload](https://docs.sequenzy.com/api-reference/media/complete-upload.md)) or a Pexels or
Unsplash photo URL. URLs with merge tags and other hosts are rejected.

**crop** `object`

The area to keep, as fractions (0 to 1) of the upright image after EXIF
orientation. Provide `crop` or `aspectRatio`, not both.

**properties**

**x** `number` *required*

Left edge as a fraction of the image width.

**y** `number` *required*

Top edge as a fraction of the image height.

**width** `number` *required*

Width as a fraction of the image width. `x + width` must not exceed 1.

**height** `number` *required*

Height as a fraction of the image height. `y + height` must not exceed 1.

**aspectRatio** `number | string`

Crops the largest area of this shape, given as width / height (`1.5`) or
`"W:H"` (`"16:9"`, `"1:1"`, `"4:5"`, `"1.91:1"`), between 1:10 and 10:1.
Provide `aspectRatio` or `crop`, not both.

**focusX** `number` (default: 0.5)

With `aspectRatio` only: the horizontal center of the crop as a fraction of
the image width. The crop moves toward it but stays inside the image.

**focusY** `number` (default: 0.5)

With `aspectRatio` only: the vertical center of the crop as a fraction of the
image height.

**altText** `string`

Accessible description stored on the new asset. Longer text is cut at 500
characters. Defaults to the generated file name.

`null` for an optional field counts as leaving it out. Every invalid request
body gets a `400` with a message naming the problem.

The cropped image keeps the original format (PNG, JPEG, WebP or GIF, including
animation); other formats become PNG or JPEG. Its longest side is at most 3,000
pixels, and the crop must be at least 8 pixels on each side.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/media/crop" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl":"https://images.sequenzy.com/email-images/comp_123/.../team.jpg",
    "aspectRatio":"16:9",
    "focusY":0.4,
    "altText":"The team at the offsite"
  }'
```

## Responses

**asset** `object`

The new media-library asset holding the cropped image, in the same shape as
[Complete Image Upload](https://docs.sequenzy.com/api-reference/media/complete-upload.md).

**crop** `object`

The crop record to store on the image block: `sourceSrc` (the original),
`croppedSrc` (equal to `asset.url`), and `x`, `y`, `width`, `height` snapped
to whole source pixels. The editor ignores a stored crop once the block's
`src` no longer equals `croppedSrc`.

**sourceWidth** `integer`

Width of the upright original in pixels.

**sourceHeight** `integer`

Height of the upright original in pixels.

```json 200 theme={null}
{
  "success": true,
  "asset": {
    "id": "media_4f1c",
    "filename": "team-cropped.jpg",
    "url": "https://images.sequenzy.com/email-images/comp_123/.../team-cropped.jpg",
    "mimeType": "image/jpeg",
    "size": "184220",
    "width": "1600",
    "height": "900",
    "altText": "The team at the offsite",
    "companyId": "comp_123",
    "createdAt": "2026-11-10T12:00:00.000Z"
  },
  "crop": {
    "sourceSrc": "https://images.sequenzy.com/email-images/comp_123/.../team.jpg",
    "croppedSrc": "https://images.sequenzy.com/email-images/comp_123/.../team-cropped.jpg",
    "x": 0,
    "y": 0.11875,
    "width": 1,
    "height": 0.5625
  },
  "sourceWidth": 1600,
  "sourceHeight": 1600
}
```

```json 400 theme={null}
{
  "success": false,
  "error": "Provide either crop or aspectRatio, not both."
}
```

```json 404 theme={null}
{
  "success": false,
  "error": "The source image was not found."
}
```

```json 503 theme={null}
{
  "success": false,
  "error": "Image cropping is busy. Try again in a moment."
}
```

Other errors: `401` without valid credentials, `403` when the key lacks
`emails:write`, `413` when the source is over 25MB or the cropped image would
be over 10MB, and `422` when the source is not a readable image. A `503` means
storage or the source download failed, or cropping is busy (a company can run
three crops at a time); it is safe to retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.