Passport Photo Crop API and Document Portrait Crop

This guide is for teams looking for a passport photo crop API, ID photo crop API, document portrait crop API, or automatic profile photo crop. The Crop plugin can use person landmarks to find the face and upper body, straighten the portrait by the person/eye-line orientation, and return a ready document-style portrait JPEG from the API.

This API prepares the document-style crop. It does not certify compliance with a specific country's official passport-photo rules. Check background, head size, eye line, print size, and local document requirements in your own application.

Recommended Payload

Use AutoMode: "Fixed" with CropModeIndex: 0 for the document/passport-style portrait preset. Set AutoStraightenMode: "Person" so the crop is straightened from person landmarks instead of the general full-image AI straighten mode. Set AspectRatio: "3 : 4", use a moderate Extend value so the document crop is not too tight, and enable fixed output sizing so the API returns a ready document-photo JPEG.

{
  "mode": "professional",
  "outputFormat": "jpeg",
  "tasks": [
    {
      "Plugin": "Crop",
      "Layer": 0,
      "User Params": {
        "AutoMode": "Fixed",
        "AutoStraightenMode": "Person",
        "CropModeIndex": 0,
        "AspectRatio": "3 : 4",
        "CustomAspectX": 3,
        "CustomAspectY": 4,
        "CenterFaceHorizontally": true,
        "CustomMargins": false,
        "Extend": 25,
        "FixSize": true,
        "FixSizePixels": 512,
        "OnlyMainSubject": false
      }
    }
  ]
}

Fields That Matter for Document Photos

Field	Recommended value	Why
AutoMode	Fixed	Uses a deterministic person crop preset.
AutoStraightenMode	Person	Uses person landmarks and eye-line orientation. Do not use AI here if the goal is a document portrait crop.
CropModeIndex	0	Uses the passport/document-style crop preset.
AspectRatio	3 : 4	Common portrait ratio for ID and document-photo workflows.
Extend	25	Adds document-photo breathing room around the head and shoulders so the crop is not an avatar-style close-up.
FixSize	true	Makes the output predictable for automated systems.
FixSizePixels	512	Returns a ready 3:4 document crop directly from the API. With this ratio and fixed size, the output is 384x512 px.

Integration Flow

1. Upload the portrait with the payload above to /retoucher/start.
2. Poll /retoucher/status/{id} until the job is completed.
3. Download the ready document-photo JPEG from /retoucher/getFile/{id}.
4. Run your own country-specific document-photo validation if required by your product.

Before and After Series

The same payload was applied to three ID-style source portraits. PortraitForID_HDR_2350 is used as the main example because it gives the cleanest document-style framing.

Source preview	Ready API crop

Heal, Dodge Burn, and Crop in One Request

For a ready retouched document portrait, put retouching plugins before Crop and keep Crop as the final task. The API then returns one flattened JPEG that is healed, enhanced with Dodge Burn, and cropped. Use conservative retouch strength for ID and passport-photo workflows, because many document systems expect a natural-looking face.

For the broader retouching workflow and plugin parameters, see All-In-One Retouching and the professional-mode task reference.

{
  "mode": "professional",
  "outputFormat": "jpeg",
  "tasks": [
    {
      "Plugin": "Heal",
      "Scale": 0,
      "Alpha1": 0.7,
      "Layer": 0
    },
    {
      "Plugin": "Dodge Burn",
      "Scale": 2,
      "Alpha1": 0.3,
      "Alpha2": 0.0,
      "Layer": 0
    },
    {
      "Plugin": "Crop",
      "Layer": 0,
      "User Params": {
        "AutoMode": "Fixed",
        "AutoStraightenMode": "Person",
        "CropModeIndex": 0,
        "AspectRatio": "3 : 4",
        "CustomAspectX": 3,
        "CustomAspectY": 4,
        "CenterFaceHorizontally": true,
        "CustomMargins": false,
        "Extend": 25,
        "FixSize": true,
        "FixSizePixels": 512,
        "OnlyMainSubject": false
      }
    }
  ]
}

Related Crop Guides

For other portrait crop presets and pose metadata, see Pose Crop. For product-object crop and mask metadata, see Subject Crop and RLE Mask. For manually tuned crop frames, use the Crop manual playground.