Reference

API Documentation

Programmatically crop, resize, and transform images using our high-performance edge infrastructure. Our REST API allows you to integrate Crop Image directly into your publishing pipelines or CMS.

Base URL

 Base URL 
https://api.cropimage.app/v1

 cURL Example Copy 
 curl -X POST https://api.cropimage.app/v1/crop \

  -F "image=@photo.jpg" \

  -F "shape=circle" \

  -F "width=300" \

  -F "format=png" 

Authentication

The Crop Image API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard. No authentication is required for free-tier usage — the API is free with a rate limit of 100 requests per minute per IP address.

Security Note: Your API keys carry significant privileges. Keep them secret and never share them in client-side code (browsers) or public repositories.

Authentication is handled via the Authorization header.

 Header 

Authorization: Bearer YOUR_API_KEY 

POST /crop

Crop a single image to a specified shape, ratio, or dimensions.

POST /v1/crop

Parameter	Description
image file / multipart	Image file to process. Supported: JPG, PNG, WEBP, GIF, BMP.
shape string	Crop shape: `circle`, `oval`, `square`, `heart`, `star`, `triangle`. Default: `rectangle`.
width number	Output width in pixels.
height number	Output height in pixels.
format string	Output format: `png`, `jpg`, or `webp`. Default: `png`.
quality number	1–100 for JPG/WebP only. Default: 92.
rotate number	Rotation in degrees. Default: 0.
flipH boolean	Flip horizontally. Default: false.
flipV boolean	Flip vertically. Default: false.

Response

 Returns image binary (default) or JSON with output_type=url 

{

  "status": "success",

  "url": "https://cdn.cropimage.app/res/abc123_300x300.png",

  "dimensions": { "w": 300, "h": 300 }

}

Code Examples

  curl -X POST https://api.cropimage.app/v1/crop \

  -F "image=@photo.jpg" \

  -F "shape=circle" \

  -F "width=300" \

  -F "height=300" \

  -F "format=png" \

  -o cropped.png

POST /batch

Crop multiple images with the same settings in a single request. Returns a ZIP archive containing all processed images.

POST /v1/batch

Parameter	Description
images[] file[] / multipart	Multiple image files to process. Same supported formats as /crop.
shape, width, height, format… mixed	Same parameters as POST /crop — applied uniformly to all images.

GET /shapes

Returns a list of all supported crop shapes with display names and descriptions.

GET /v1/shapes

 JSON Response 

{

  "shapes": [

    { "id": "circle", "label": "Circle" },

    { "id": "heart", "label": "Heart" },

    { "id": "star", "label": "Star" }

  ]

}

GET /presets

Returns a list of social media presets with recommended dimensions for each platform.

GET /v1/presets

 JSON Response 

{

  "presets": [

    { "id": "instagram-square", "label": "Instagram Square", "width": 1080, "height": 1080 },

    { "id": "youtube-thumbnail", "label": "YouTube Thumbnail", "width": 1280, "height": 720 }

  ]

}

Rate Limits

To ensure fair usage across all users, the following rate limits apply:

Plan	Requests / Minute	Max File Size
Free (no key)	100 / min per IP	10 MB
Pro	500 / min	50 MB
Enterprise	Custom	Unlimited

Error Codes

The API uses standard HTTP status codes. All errors return a JSON body with a code and message field.

HTTP Status	Code	Description
400	invalid_params	Missing or invalid request parameters.
401	unauthorized	Invalid or missing API key.
413	file_too_large	Image exceeds the maximum file size for your plan.
415	unsupported_format	File format is not supported.
429	rate_limit_exceeded	Too many requests. Slow down and retry.
500	server_error	Internal server error. Try again later.

Interactive Request Builder

Test the API in real-time with your parameters. Note: This uses a demo key with rate limits.

Endpoint

Shape

Output Format

Response Console

> Waiting for request...

200 OK