Introduction

The Image Editor REST API allows your application to take a source image as input and produce a modified image that has been processed by one or more ImageGear .NET image editing operations. See the ImageEditorRestAPI Sample for an example on how to use the API in an application.

Available URLs

POST /imageGear/api/v1/imageEditors

Creates and starts a new image editor process.

An image editor represents a process that runs on the server and transforms an image according to one of several processing options.

The server process to edit images is started by this request, but a response is sent before the process is complete. Use the GET /imageGear/api/v1/imageEditors/{processId} URL below to get the state and results of an in-progress or completed image editing process.

1. The image editor supports the following file types for input and output:

   • BMP
   • CLP
   • CUR
   • GIF
   • ICO
   • JPEG
   • PNG
   • TIFF

2. The image editor works for single-page files only. If the input file contains more than one page, it will process the first page and ignore the rest.

Request

Request Headers

Request Body

JSON object conforming to the following:

• input

  • source (Object) Required. An object that defines the source image.

    • fileId (String) Required. The ID of the work file which represents the source image that will be edited. See the Work File API topic to find out how to upload a work file.

  • operations (Array) Defines what type of image editing operations are to be performed on the input image and specifies the parameters to be used for the operation. The values in this array should be objects which contain the properties listed below. Operations will be performed in the order in which they were present in the array.

    • type (String) Required. The type of operation to be performed. Must be one of the following values:
      • "resize" - Retains the same image, but either increases the number of pixels (interpolating to determine the color values for the new ones), or decreases the number of pixels.
      • "crop" - Removes part of the image.
      • "rotate" - Changes the geometry of the image (rotates an image).
      • "flip" - Changes the geometry of the image (flips an image).
      • "convertColorSpace" - Converts the image to a new color space.
      • "deskew" - Removes the detected skew angle for a bitonal image.

    In addition to the type argument, the operation object should contain the following additional properties according to the desired operation type:

    • resize

      • width (Integer) Required. - New image width.

      • height (Integer) Required. - New image height.

      • interpolationOptions (String) - This method processes all channels of the image as well as the image's ROI, if it exists. Interpolation options are ignored when resizing vector images. Applicability of interpolation options to raster images depend on the color space and bit depth of the image. The following table specifies applicability of interpolation options to different types of raster images.

        Option	Bitonal images	Non-bitonal images
        none	Yes	Yes
        average	Only if both new width and height are not smaller than original width and height.	Yes, except indexed images where palette is not grayscale or inverted grayscale.
        bilinear	Only if both new width and height are not smaller than original width and height.	Yes, except indexed images where palette is not grayscale or inverted grayscale.
        nearestNeighbor	Yes	Yes
        grayscale	Only if both new width and height are not greater than original width and height.	No
        preserveWhite	Only if both new width and height are not greater than original width and height.	No
        preserveBlack	Only if both new width and height are not greater than original width and height.	No
        bicubic	No	Yes, except indexed images where palette is not grayscale or inverted grayscale.

    • crop

      • left (Integer) Required. - Left border of the new image.
      • top (Integer) Required. - Top border of the new image.
      • width (Integer) Required. - Width of the new image.
      • height (Integer) Required. - Height of the new image.

    • rotate

      • angle (Float) Required. - Clockwise rotation angle in degrees.
      • mode (String) Rotation mode. Defines how the bounds of the image are adjusted to accommodate rotation of the image. Unused when angle is a multiple of 90 degrees. Mode accepts the two following values:
        • "clip" - Clips rotated image to keep the image dimensions unchanged.
        • "expand" - Expands the size of the image to retain the entire rotated image. This is the default behavior.
      • background (Float Array) - Background color to fill the out of picture area; a background color not being provided will result in a black background. Example: [1.0, 1.0, 1.0, 1.0] for a white background in an image with 3 color channels and alpha.

        Note: The background property is unused when angle is a multiple of 90 degrees.

      • interpolation (String) - Interpolation to use for rotation. Must be one of the following values:
        • "bicubic" - Bicubic interpolation.
        • "bilinear" - Bilinear interpolation.
        • "none" - No interpolation.

    • flip

      • direction (String) Required. - Defines flip direction. Must be one of the following values:
        • "horizontal" - Flips the image across the Y-Axis.
        • "vertical" - Flips the image across the X-Axis.

    • convertColorSpace

      • newColorSpace (String) Required. - One of the valid conversion color spaces. Must be one of the following values:
        • "cmy" - CMY color space.
        • "cmyk" - CMYK color space.
        • "cmykex" - CMYK + Extra channel.
        • "gy" - Grayscale color space.
        • "gya" - Grayscale + Alpha channel.
        • "gypa" - Grayscale + premultiplied alpha channel.
        • "gypaex" - Grayscale + premultiplied alpha channel + extra channel.
        • "hls" - HLS color space.
        • "ihs" -IHS color space.
        • "lab" - LAB color space.
        • "rgb" - RGB color space.
        • "rgba" - RGB + alpha channel.
        • "rgbaex" - RGB + alpha + extra channel.
        • "rgbex" - RGB + extra channel.
        • "rgbpa" - RGB + premultiplied alpha channel.
        • "rgbpaex" - RGB + premultiplied alpha channel + extra channel.
        • "ycbcr" - YCbCr color space.
        • "yiq" - YIQ color space.
        • "yuv" - YUV color space.
      • translatePixelValues (Boolean) - Flag indicating whether to change pixel values according to the new color space.
      • backgroundColor (Float Array) - If conversion removes the alpha channel from the image, the image is composited over a solid background specified by backgroundColor. Background color should be in the same color space as the original image, but without the Alpha channel. For example, if the original image is in RGBA color space and newColorSpace is CMYK, background color should have an RGB color space and backgroundColor array should have 3 elements. The method will first transform the image into RGB and then to CMYK. Each value in the array must be in the range [0, 1].

    • deskew

      • angleThreshold (Float) - The minimum detected skew angle to correct, expressed as degrees in the clockwise direction. Must be in range (-89.0, 89.0). If omitted, angleThreshold defaults to 0.25.
      • mode (String) - Defines the rotation mode and how the bounds of the image are adjusted to accommodate rotation of the image. If omitted, mode defaults to "clip".
        • "clip" - Clips the deskewed image to keep its dimensions unchanged.
        • "expand" - Expands the size of the image to retain the entire deskewed image.
      • background (Float Array) - Specifies the background color used to fill the empty space created after deskewing an image; if omitted, the background color defaults to white. Example: [1.0] for a white background in an image with one color channel.

• dest (Object) An object that defines the properties of the output image returned by the process.

  • fileFormat (String) The file format of the output image. Default is ‘tif’. Must be one of the following values:
    • bmp - Bitmap Image
    • clp - Windows Clipboard Image
    • cur - Windows Cursor Image
    • gif - Graphics Interchange (Greyscale Images Only)
    • ico - Windows Icon
    • jpg - JPEG Image
    • png - Portable Network Graphics Image
    • tif - Tag Image File Format

• minSecondsAvailable (Integer) The minimum number of seconds this image editor status will remain available via a GET request. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime [central configuration] parameter.

Successful Response

Response Body

JSON object with the following properties:

• input (Object) A copy of the request body input object.
• processId (String) The id of the new image editor process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the image editor will be deleted.
• state (String) The current state of the image editor process running on the server. The response will always be "processing".

Error Responses

Example

Request

POST /imageGear/api/v1/imageEditors
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "operations": [
      {
        "type": "flip",
        "direction": "horizontal"
      }
    ]
  },
  "minSecondsAvailable": 60
}

Response

HTTP 200 OK
Content-Type: application/json
{
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-05T13:24:35.395Z",
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "operations": [
      {
        "type": "flip",
        "direction": "horizontal"
      }
    ]
  },
  "state": "processing"
}

GET /imageGear/api/v1/imageEditors/{processId}

Gets the state and result of an existing image editor process created by POST /imageGear/api/v1/imageEditors.

Requests can be sent to this URL repeatedly while the state is "processing".

When the state is "complete", the response will include the work file id of the processed output image.

If the image editor process encounters an error, the state property will be "error" and the errorCode property will contain an error code string.

Request

Parameters

Response Body

JSON object with the following properties:

• input (Object) A copy of the POST /imageGear/api/v1/imageEditors request body input object we accepted to create the image editor process.
• processId (String) The id of the image editor process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the image editor will be deleted.
• state (String) The current state of the image editor process running on the server. The following values are allowed:
  • "processing" - The image editor is in progress.
  • "complete" - The image editor is completed.
  • "error" - The image editor returns an error.
• errorCode (String) An error code string if a problem occurred during the image editor process. Only present when state is "error".
• output (Object) Describes the output image. Only present when state is "complete".
  • fileId (String) The ID of the work file which represents the source image that was edited. See the Work File API topic to find out how to download a work file.

Error Responses and JSON Error Codes

Example

Request

GET /imageGear/api/v1/imageEditors/iFhSZRvrz2vtFjcTSi9Qlg

Successful Response

When the image editor process completes with no errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-05T13:24:35.395Z",
  "state": "complete",
  "output": {
    "fileId": "fl6Ac234pZITVFWy2cVsWR"
  }
}

Error Responses

Response when an image editor process does not exist for the given processId:

HTTP 404
Content-Type: application/json
{
  "errorCode": "ResourceNotFound",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Response when an image editor process did exist for the given processId, but has passed its expiration time:

HTTP 410
Content-Type: application/json
{
  "errorCode": "ResourceExpired",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Response when source document is a file format that is not supported by the Image Editor API:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnsupportedFileFormat",
  "errorDetails": {
    "in": "process",
    "at": "input.source.fileId"
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when source document uses a pixel format not supported for one of the Image Editor API operations used:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnsupportedBitDepth",
  "errorDetails": {
    "in": "process",
    "at": "input.operations[4].image",
    "operation": "deskew"
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}