Skip to main content
POST
Crop 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, then crop the uploaded URL.

Request

string
required
Hosted URL of the original image: a media-library URL (for example from Complete Image Upload) or a Pexels or Unsplash photo URL. URLs with merge tags and other hosts are rejected.
object
The area to keep, as fractions (0 to 1) of the upright image after EXIF orientation. Provide crop or aspectRatio, not both.
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.
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.
number
default:"0.5"
With aspectRatio only: the vertical center of the crop as a fraction of the image height.
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.

Responses

object
The new media-library asset holding the cropped image, in the same shape as Complete Image Upload.
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.
integer
Width of the upright original in pixels.
integer
Height of the upright original in pixels.
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.