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 convert endpoint transforms a media file from one format to another and saves the result as a new file under MEDIA_ROOT/converted/. The source file is never modified. Supported media categories include images (via Pillow), audio and video (via ffmpeg), and PDF-to-image extraction (via pdf2image + Poppler). Each category requires its own dependency to be available in the environment.

​
Endpoint

POST /var-cms/api/media/convert/

​
Authentication

Login required. Requests must carry a valid authenticated Django session. The endpoint is protected by Django’s login_required decorator.

​
Supported Conversions

Media TypeSource FormatsTarget FormatsDependency
Imagejpeg, jpg, png, webp, bmp, tiff, gifjpeg, jpg, png, webp, bmp, tiff, gifPillow
Audiomp3, wav, ogg, flac, aac, m4amp3, wav, ogg, flac, aac, m4affmpeg
Videomp4, webm, avi, mov, mkvmp4, webm, avi, mov, mkvffmpeg
PDF → Imagespdfpng, jpg, jpegpdf2image + Poppler
Audio and video conversion uses ffmpeg via subprocess. The ffmpeg binary must be accessible on the system PATH of the process running Django. PDF conversion uses pdf2image (which wraps Poppler’s pdftoppm). These are optional — the endpoint returns a clear install_hint in the error body if a required tool is missing.

​
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 file inside MEDIA_ROOT. Do not include the MEDIA_URL prefix.Example: var_cms/images/2024/01/photo.png
​
target_fmt
string
required
Desired output file extension (without the leading dot). The value is lowercased and any leading . is stripped automatically. The endpoint uses this to determine both the conversion pathway and the output filename.Examples: webp, mp3, mp4, png

​
Response

​
Image success — 200 OK

​
url
string
Absolute media URL of the converted file. Example: /media/converted/7b3c9a12ef56.webp
​
path
string
Relative storage path of the output file within MEDIA_ROOT. Example: converted/7b3c9a12ef56.webp
​
type
string
Always "image" for image conversions.

​
Audio / Video success — 200 OK

​
url
string
Absolute media URL of the converted file.
​
path
string
Relative storage path of the output file within MEDIA_ROOT.
​
type
string
"audio" when the target format is an audio format; "video" when it is a video format.

​
PDF success — 200 OK

​
type
string
Always "pdf_pages" for PDF-to-image conversions.
​
pages
array
Ordered array of media URLs, one per extracted page. Each page is saved as a separate PNG file under MEDIA_ROOT/converted/.
​
count
number
Total number of pages extracted from the PDF.

​
Error Responses

​
error
string
Human-readable error message. Returned alongside an optional install_hint field for dependency errors.
Statuserror valueinstall_hintCause
400"file_path and target_fmt required"—One or both required POST parameters were missing or empty.
400"Unsupported conversion: X → Y"—The source/target format combination is not handled by any converter.
404"File not found"—The resolved path does not exist inside MEDIA_ROOT.
500"Pillow not installed"—Pillow is missing; required for image conversions.
500"ffmpeg not found. Install with: sudo apt install ffmpeg""sudo apt install ffmpeg"The ffmpeg binary is not on the system PATH.
500"pdf2image not installed. Run: uv add pdf2image""uv add pdf2image"The pdf2image package is missing; required for PDF conversions.

​
Requirements & Optional Extras

Pillow is required for image conversion. Audio/video conversion and PDF extraction are opt-in dependencies: 
# Image conversion (Pillow):
pip install django-var-cms pillow
# or with uv:
uv add django-var-cms pillow

# PDF page extraction (adds pdf2image + Poppler):
uv add pdf2image

# Audio / video conversion via system ffmpeg:
sudo apt install ffmpeg          # Debian / Ubuntu
brew install ffmpeg              # macOS
ffmpeg is not a Python package — it must be installed as a system binary. The endpoint checks for its presence by running which ffmpeg and returns HTTP 500 with install_hint if it is absent.

​
Example

​
Request

curl -X POST http://localhost:8000/var-cms/api/media/convert/ \
  -H "Cookie: sessionid=<your-session>" \
  -d "file_path=var_cms/images/2024/01/photo.png&target_fmt=webp"

​
Response

{
  "url": "/media/converted/7b3c9a12ef56.webp",
  "path": "converted/7b3c9a12ef56.webp",
  "type": "image"
}

​
PDF Example Response

{
  "type": "pdf_pages",
  "pages": [
    "/media/converted/a1b2c3d4e5f6.png",
    "/media/converted/b2c3d4e5f6a7.png",
    "/media/converted/c3d4e5f6a7b8.png"
  ],
  "count": 3
}

​
Conversion Details

​
Images

Pillow opens the source file, converts to the target format, and saves at quality 90. Images in RGBA or P mode are automatically converted to RGB when the target format is JPEG. Output files are saved to converted/{uuid.hex[:12]}.{ext} via Django’s default_storage.

​
Audio & Video

ffmpeg is invoked via subprocess with a -y -i <source> <output> command and a 120-second timeout. The converted file is written to a temporary path, read into memory, then saved via Django’s default_storage. The type field in the response is "audio" if the target format is in the audio formats set, otherwise "video".

​
PDF

pdf2image calls Poppler’s pdftoppm at 150 DPI, producing one PIL Image object per page. Each page is saved as a PNG to MEDIA_ROOT/converted/ and its URL is appended to the pages array.

Build docs developers (and LLMs) love

Get started for freeTalk to us