API: Legacy croppola requests
Crops a picture using the croppola algorithm, and returns either the crop coordinates or the cropped picture.
This is the old Croppola API. We strongly recommend using the new API.
Uploading and processing an image
Request
POST /croppola/image.json?apiKey=ABCD...&aspectRatio=1.5& x=5%25& y=5%25& width=90%25& height=90%25& algorithm=croppola& scaledMaximumWidth=200& scaledMaximumHeight=200
PNG OR JPEG IMAGE DATA
| apiKey | Your API key. |
| algorithm | The algorithm used to determine the crop location. Use croppola for selecting the most suitable crop or center for a crop in the image center. |
| aspectRatio | The desired aspect ratio, expressed as factor (e.g. 1.5) or ratio (e.g. 3:2). For portrait crops, invert the aspect ratio (e.g. 2:3). |
| width, height | The crop size. Parameters can be provided as percentage of the original image dimensions, or as pixels. |
| x, y | Crop coordinates for fixed crops. Parameters can be provided as percentage of the original image dimensions, or as pixels. |
| maximumWidth, maximumHeight | Desired crop size as percentage of the original image, or as pixels. A rectangle of the desired aspect ratio is fitted within the maximum dimensions. |
| scaledMaximumWidth, scaledMaximumHeight | If provided, the final crop is scaled down to these dimensions. This is useful to create thumbnail images or previews. |
The crop size can be provided in one of the following ways:
- width and height
- aspectRatio and width
- aspectRatio and height
- aspectRatio, maximumWidth, and maximumHeight (largest fitting rectangle)
- aspectRatio, minimumWidth, and minimumHeight (smallest fitting rectangle)
Response
200 OK
{ "algorithm": "croppola", "cropHeight": 2088, "cropWidth": 3712, "cropX": 690, "cropY": 0, "dominantColors": [ ], "faces": [ ], "height": 2088, "imageHeight": 2088, "imageWidth": 4640, "scaledHeight": 2088, "scaledWidth": 3712, "token": "9621bb2cf1a35d3c72c71983fe7cdb1146d02ed46062f26f489df2b3d239df78", "width": 3712, "x": 690, "y": 0 }
| token | The token for further requests. |
| algorithm | The algorithm used to determine the crop coordinates. |
| imageWidth, imageHeight | The dimensions of the original image. |
| x, y, width, height | The high-resolution crop coordinates. |
| cropX, cropY, cropWidth, cropHeight | The crop coordinates rounded to the nearest pixel. |
| scaledWidth, scaledHeight | The final crop size after scaling. |
| faces | Not implemented right now. |
| dominant colors | Not implemented right now. |
The file name (e.g. image.json) can be chosen freely, but the file extension determines the output:
- *.json: JSON with the crop parameters as described above.
- *.jpg: the cropped image in JPEG format.
- *.png: the cropped image in PNG format.
Processing a previously uploaded image
Request
GET /croppola/9621bb2cf1a3.../image.jpg?apiKey=ABCD...&aspectRatio=1.5& x=5%25& y=5%25& width=90%25& height=90%25& algorithm=croppola& scaledMaximumWidth=200& scaledMaximumHeight=200
As above, but uses a previously uploaded image. Note that token are valid for about 1 h, as images are deleted afterwards.
Response
200 OK
JSON ANALYSIS, PNG OR JPEG IMAGE DATA
As above.
Downloading a cropped picture
Request
GET /croppola/9621bb2cf1a3.../download/image.jpg?apiKey=ABCD...&aspectRatio=1.5& x=5%25& y=5%25& width=90%25& height=90%25& algorithm=croppola& scaledMaximumWidth=200& scaledMaximumHeight=200
As above, but adds the HTTP headers to tell the browser to save the cropped picture to disk rather than displying it in a browser tab.
Response
200 OK
Content-Disposition: attachment
JSON ANALYSIS, PNG OR JPEG IMAGE DATA
As above.