Crop

Crop is a professional-mode plugin for image straightening and crop geometry. In AI mode it predicts the straighten angle. In manual mode it applies the crop frame supplied in User Params.

Use the Crop manual playground to tune manual crop parameters visually and copy the User Params JSON into your API payload.

Input Image

The examples below use this tilted source image.

Parameters

Field	Type	Default	Description
Plugin	string	required	Use Crop.
Layer	integer or boolean	0	1 writes prediction metadata to the ZIP result.json. 0 returns a flattened image.
User Params.AutoStraightenMode	string	Manual	AI and Person run the straighten predictor. Manual uses the supplied manual parameters.
User Params.AspectRatio	string	absent	Accepted values include Free, Original, Custom, Square, 2 : 3, 4 : 5, and 16 : 9.
User Params.Angle	number	absent	Manual rotation angle in degrees for flattened manual crop output.
User Params.ManualCenterX / ManualCenterY	number	0.5	Manual crop center in normalized crop-center range.
User Params.ManualArea	number	absent	Manual crop area relative to the maximum crop for the selected angle and aspect ratio. If omitted in flattened manual mode, Crop is a no-op.
User Params.ManualAspectRatio	number	absent	Manual crop aspect ratio used when AspectRatio is Free.
User Params.CustomAspectX / CustomAspectY	number	absent	Custom aspect components used when AspectRatio is Custom.

Example 1 - AI Straighten Metadata

This request asks the API to predict the straighten angle and return a ZIP archive. With Layer: 1, the Crop plugin does not return an image layer; it writes prediction metadata into result.json.

{
  "mode": "professional",
  "outputFormat": "zip",
  "tasks": [
    {
      "Plugin": "Crop",
      "Layer": 1,
      "User Params": {
        "AutoStraightenMode": "AI",
        "AspectRatio": "Original"
      }
    }
  ]
}

Successful /retoucher/start output:

{
  "status": 200,
  "id": "crop-ai-metadata-job-id"
}

When the job is completed, download the ZIP with /retoucher/getFile/{id}. The archive contains result.json with Crop prediction metadata:

{
  "jsonVersion": "1",
  "plugins": [
    {
      "AI predicted": {
        "Angle": 1.9124702215194702,
        "RotInvariant": 0.0014798319898545742
      },
      "operationIndex": 0,
      "pluginName": "Crop"
    }
  ]
}

AI predicted.Angle is the public straighten angle used by Crop auto-rotate. AI predicted.RotInvariant is the probability that it is impossible to infer a horizon or straightening angle from the image contents.

Download AI metadata ZIP or download result.json.

Example 2 - AI Straighten Image

This request uses the same AI predictor but sets Layer: 0, so the result file is the straightened image.

{
  "mode": "professional",
  "outputFormat": "jpeg",
  "tasks": [
    {
      "Plugin": "Crop",
      "Layer": 0,
      "User Params": {
        "AutoStraightenMode": "AI",
        "AspectRatio": "Original"
      }
    }
  ]
}

Successful /retoucher/start output:

{
  "status": 200,
  "id": "crop-ai-image-job-id"
}

Successful /retoucher/getFile/{id} output is a binary JPEG image. The image is rotated by the predicted angle and cropped to the maximum valid crop for the requested aspect ratio. The live example result is 3417x4397.

Example 3 - Manual Square Crop

Manual mode uses the crop geometry in User Params. The Crop manual playground is the easiest way to tune these fields. This example uses Crop plugin settings exported from the desktop UI, reduced to the server-side fields needed for a manual square crop. In the live cloud run for this example, the request succeeded with the default image output, so outputFormat is intentionally omitted.

{
  "mode": "professional",
  "tasks": [
    {
      "Plugin": "Crop",
      "Layer": 0,
      "User Params": {
        "AspectRatio": "Square",
        "AutoStraightenMode": "Manual",
        "Angle": 0.0,
        "ManualCenterX": 0.5543881336733065,
        "ManualCenterY": 0.1795774589095692,
        "ManualArea": 0.7982946634292603
      }
    }
  ]
}

Successful /retoucher/start output:

{
  "status": 200,
  "id": "crop-manual-job-id"
}

Each successful /retoucher/getFile/{id} response is a binary JPEG image. The three live example outputs below are square crops at 1191x1191. If ManualArea is missing in flattened manual mode, the Crop plugin leaves the image unchanged.

Common Flow

1. Submit a multipart /retoucher/start request with file, token, and Crop payload.
2. Poll /retoucher/status/{id} until state is completed.
3. Download the result with /retoucher/getFile/{id}.

The Crop API uses the same authentication, polling, and file download flow as the rest of the Cloud Retouching API. See the main API documentation for endpoint details and error codes.