Media
Crop Image
Crop a media-library image into a new hosted image
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
Other errors:
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.
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.