Accessing the qCrop Server

All qCrop Services require a running instance of the qCrop Server. Provisioning of this server depends on the kind of hosting and service agreement and is beyond the scope of this book. Please contact for licensing options.

For the purposes of the documentation we provide a free service at, so you can try the qCrop Services on a live system. Please respect, that this service is not allowed for other purposes than familiarization with the qCrop system. In particular it is not allowed to use this server for real live production or commercial purposes!

The qCrop Server is typically (but not necessarily) operated at standard port 80 via TSL on a dedicated domain/subdomain.

qCrop Service Short Reference

If a GET request is sent to the qCrop Service URL without any parameters, a short, up-to-date server description is returned as plain text:


 QCROP Webservice
    (c) 2020 append[x] GmbH

    qCrop: Naturally intelligent Image Cropping as a Microservice
    Learn more at


      GET /crop-to-file/<crop-parameters>/<image-url>

          crops the image at <image-url> according to the parameters
          defined in <crop-parameters> and delivers the target image
          as result.
          If qCrop cropping hints exist in the source image, they will
          be respected, otherwise a centered crop is executed.

          The cropping parameters have to be delimited with a colon (:).
          Supported parameters are:
          - w<width>          : width of the target image in pixels
          - h<height>         : height of the target image in pixels
          - a<WxH>            : aspect ratio as WIDTHxHEIGHT
          - m<mime>           : mimetype of the target image
                                (jpg, tif, png)
          - q<percent>        : compression quality in percent for target
                                (only relevant for JPG target)
          - d<X>              : target resolution in dpi
          - d<XxY>            : target resolution in dpi with
                                different values for x and y
          - prRes<ValueUnit>  : print resolution in ppi or ppcm
          - phyW<ValueUnit>   : physical width of the target image
                                in cm, mm or inch
          - phyH<ValueUnit>   : pyhsical height of the target image
                                in cm, mm or inch
          - c<ProfileName>    : convert target to color profile
                                (See full documentation for available
                                color profiles)
          - stripColorProfile : remove color profile from target image
          - nocache           : force reload of source image

          Illegal parameters are silently ignored.

      GET /crop-to-data/<crop-parameters>/<image-url>

          takes an array of target aspect ratios as parameter and returns
          a JSON object with cropping rectangles as pixels or percentage.


      GET /webclient/<client-parameters>/<image-url>

          invokes the qCrop webclient application for the image at


      GET /cache/<image-url>

          retrieves the given file at <image-url> and copies it to the
          local server cache; then builds dependent variants like the
          webclient preview and digital primary file within the cache.
          Preloading images to the cache with this command
          significantly speeds up the webclient and cropping process.

          Returns a full dump of all cache related data of <image-url>
          for diagnostic purposes.

      GET /metadata/<image-url>

          retrieves common metadata (Exif/XMP/NITF) and qCrop metadata
          of the image at <image-url> for diagnostical purposes.

© 2020-2021, append[x] GmbH, Egling-Endlhausen