Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rahul-baberwal/django-var-cms/llms.txt

Use this file to discover all available pages before exploring further.

The crop endpoint accepts a media file path and crop coordinates, applies optional rotation and flip transforms, saves the result as a new file under MEDIA_ROOT/crops/, and returns a JSON response with the URL, path, format, and dimensions of the cropped image. The source image is never modified — a fresh file with a UUID-based name is always written.

​
Endpoint

POST /var-cms/api/media/crop/

​
Authentication

Login required. Requests must be made with a valid authenticated Django session. The endpoint is protected by Django’s login_required decorator and rejects unauthenticated requests with a redirect to the login page.
This endpoint is called automatically by the built-in image cropper modal UI (powered by Cropper.js). You only need to call it directly if you are building a custom integration outside of the standard django-var-cms admin interface.

​
Request Parameters

Send parameters as application/x-www-form-urlencoded (standard HTML form POST body).
​
file_path
string
required
Relative media path of the source image inside MEDIA_ROOT. Do not include the MEDIA_URL prefix.Example: var_cms/images/2024/01/photo.jpg
​
x
number
required
Left offset of the crop box in pixels, measured from the left edge of the (post-transform) image. Accepted as a float and converted to int internally.
​
y
number
required
Top offset of the crop box in pixels, measured from the top edge of the (post-transform) image. Accepted as a float and converted to int internally.
​
w
number
required
Width of the crop box in pixels. Accepted as a float and converted to int internally. Must be greater than 0 for cropping to be applied.
​
h
number
required
Height of the crop box in pixels. Accepted as a float and converted to int internally. Must be greater than 0 for cropping to be applied.
​
rotate
number
default:"0"
Rotation angle in degrees. Applied after flipping and before the crop is taken. Positive values rotate clockwise; the image canvas expands to fit the rotated result (expand=True).
​
scale_x
number
default:"1"
Horizontal flip control. Pass -1 to mirror the image left-to-right (FLIP_LEFT_RIGHT), 1 for normal orientation.
​
scale_y
number
default:"1"
Vertical flip control. Pass -1 to mirror the image top-to-bottom (FLIP_TOP_BOTTOM), 1 for normal orientation.
​
format
string
Output image format. Accepted values: jpeg, png, webp. When omitted, the format defaults to the same format as the source image, falling back to PNG if the source extension is unrecognised. JPEG output automatically converts RGBA images to RGB.

​
Response

​
Success — 200 OK

​
url
string
Absolute media URL of the saved crop, served from MEDIA_URL. Use this to display or reference the image in your application.Example: /media/crops/a3f9b12c4d5e.webp
​
path
string
Relative storage path of the crop within MEDIA_ROOT, as returned by Django’s default_storage.Example: crops/a3f9b12c4d5e.webp
​
format
string
Pillow format string of the saved output. One of JPEG, PNG, or WEBP.
​
size
array
Two-element integer array [width, height] representing the pixel dimensions of the cropped image.Example: [400, 300]

​
Error Responses

​
error
string
Human-readable error message. Returned with one of the following HTTP status codes:
Statuserror valueCause
400"file_path required"The file_path POST parameter was missing or empty.
400"Invalid params: ..."One or more of x, y, w, h, rotate, scale_x, scale_y could not be parsed as a number (ValueError or TypeError).
404"File not found"The resolved absolute path does not exist inside MEDIA_ROOT.
500"Pillow not installed. Run: uv add pillow"The Pillow library is not available in the current Python environment.

​
Requirements

Pillow is a required dependency. The crop endpoint will return HTTP 500 if Pillow is not installed. Install it alongside the package:
pip install django-var-cms pillow
# or with uv:
uv add django-var-cms pillow
The source file must reside within MEDIA_ROOT. The endpoint sanitises file_path by stripping any leading slash and MEDIA_URL prefix before joining with MEDIA_ROOT, so passing the raw MEDIA_URL-prefixed URL is safe.

​
Example

​
Request

curl -X POST http://localhost:8000/var-cms/api/media/crop/ \
  -H "Cookie: sessionid=<your-session>" \
  -d "file_path=var_cms/images/2024/01/photo.jpg&x=10&y=20&w=400&h=300&format=webp"

​
Response

{
  "url": "/media/crops/a3f9b12c4d5e.webp",
  "path": "crops/a3f9b12c4d5e.webp",
  "format": "WEBP",
  "size": [400, 300]
}

​
Transform Order

Transforms are applied in the following order before the crop box is extracted:
  1. Flip horizontal — scale_x = -1 flips left-to-right (FLIP_LEFT_RIGHT).
  2. Flip vertical — scale_y = -1 flips top-to-bottom (FLIP_TOP_BOTTOM).
  3. Rotate — the image is rotated by -rotate degrees (i.e. positive rotate values rotate clockwise) with canvas expansion enabled (expand=True).
  4. Crop — the region (x, y, x+w, y+h) is extracted from the transformed image.
This matches the coordinate system used by Cropper.js, which reports crop coordinates relative to the already-transformed canvas.

Build docs developers (and LLMs) love

Get started for freeTalk to us