Image operations

This guide covers operations that edit an image without changing its purpose: resizing, cropping, and rotating. Resizing is a dedicated operation, while cropping and rotating are options you set on a normal image conversion. To shrink file size see Compress files, and for generating preview-sized images see Create thumbnails.

Resize an image

The resize-image operation scales an image to new dimensions. Provide a width and/or height (in the unit set by resize_by, e.g. px or perc), and control how the source fits the target box with resize_handling. Optionally force an aspect ratio with aspect_ratio (e.g. "16:9") or set the output format with resize_target.

Submit a job that resizes an image to 800×600 pixels:

{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "resize-image",
      "options": {
        "width": 800,
        "height": 600,
        "resize_by": "px",
        "resize_handling": "keep_aspect_ratio_crop"
      }
    }
  ]
}

curl -X POST https://api.api2convert.com/v2/jobs \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d @job.json

Crop an image

Cropping happens on a regular image conversion: target the output image format and set the four crop options together. All four are required as a set — the origin point (top-left corner) plus the size of the region to keep.

Keep a 400×300 region starting 50 pixels in from the top-left of a JPG:

{
  "conversion": [
    {
      "category": "image",
      "target": "jpg",
      "options": {
        "crop_origin_x": 50,
        "crop_origin_y": 50,
        "crop_width": 400,
        "crop_height": 300
      }
    }
  ]
}

Rotate an image

On an image conversion, the rotate option turns the image clockwise by the given number of degrees.

{
  "conversion": [
    {
      "category": "image",
      "target": "jpg",
      "options": {
        "rotate": 90
      }
    }
  ]
}

Live options

Pick an operation or image target to see its live options. Browse every target in the format explorer.