Skip to main content
The crop operation extracts a region from a source image. You can define the region manually with pixel coordinates, or let the engine choose the best region automatically using gravity modes.

​
Parameters

​
operation
string
required
Must be "crop".
​
input
string
required
Path to the source image.
​
output
string
required
Path for the cropped output file.
​
rect
object
Manual crop rectangle. Either rect or gravity is required.
​
gravity
string
Smart crop mode. Either rect or gravity is required. When using gravity, width and height are also required.
ValueDescription
centerCrop centered on the image
focal_pointCrop centered on the coordinates set by focal_x / focal_y
entropyCrop the region with the highest brightness variance
​
focal_x
number
default:"0.5"
Horizontal focal point as a normalized value between 0.0 (left edge) and 1.0 (right edge). Used when gravity is focal_point.
​
focal_y
number
default:"0.5"
Vertical focal point as a normalized value between 0.0 (top edge) and 1.0 (bottom edge). Used when gravity is focal_point.
​
width
number
Target output width in pixels. Required when using gravity.
​
height
number
Target output height in pixels. Required when using gravity.
​
format
string
default:"same as input"
Output format: png, jpeg, webp, or avif.
​
quality
number
default:"85"
Encode quality for JPEG and WebP outputs. Range: 1–100.
​
inline
boolean
default:"false"
When true, the output file is also returned as a base64-encoded string in data_base64.
Use focal_point gravity when the subject position is known in advance — for example, a face in a profile photo or a product in a hero image. Store the focal coordinates alongside the original asset and pass them through on every crop, so the result stays correct regardless of output dimensions.

​
Go client

func (c *Client) Crop(ctx context.Context, job *CropJob) (*JobResult, error)

type CropJob struct {
    Operation string    `json:"operation"`
    Input     string    `json:"input"`
    Output    string    `json:"output"`
    Rect      *CropRect `json:"rect,omitempty"`
    Gravity   string    `json:"gravity,omitempty"`
    FocalX    *float64  `json:"focal_x,omitempty"`
    FocalY    *float64  `json:"focal_y,omitempty"`
    Width     *uint32   `json:"width,omitempty"`
    Height    *uint32   `json:"height,omitempty"`
    Format    string    `json:"format,omitempty"`
    Quality   *uint8    `json:"quality,omitempty"`
    Inline    bool      `json:"inline,omitempty"`
}

type CropRect struct {
    X      uint32 `json:"x"`
    Y      uint32 `json:"y"`
    Width  uint32 `json:"width"`
    Height uint32 `json:"height"`
}

​
Examples

​
Manual rectangle crop

Extract a precise pixel region from the source image.
{
  "operation": "crop",
  "input": "photo.jpg",
  "output": "cropped.jpg",
  "rect": {
    "x": 100,
    "y": 50,
    "width": 800,
    "height": 600
  },
  "format": "jpeg",
  "quality": 90
}

Build docs developers (and LLMs) love

Get started for freeTalk to us