Django REST Framework

Generate imgproxy URLs using DRF serializers. Return a single image URL or a dictionary of named variants using transformations configured in Django settings.

Installation

uv add 'imgproxykit[drf]'

poetry add 'imgproxykit[drf]'

pip install 'imgproxykit[drf]'

The extra installs Django and Django REST Framework.

Configuration

Define IMGPROXYKIT in your Django settings. This integration shares the client, named transformations, variant sets, and source resolver with the Django integration:

from imgproxykit import Transform
from imgproxykit.integrations.django import SettingsDict

thumbnail = Transform(width=300, height=300, format='webp')

IMGPROXYKIT: SettingsDict = {
    'client': {
        'base_url': 'https://imgproxy.example.com',
        # Use your server's key and salt.
        'key': '736563726574',
        'salt': '73616c74',
    },
    'transforms': {'thumbnail': thumbnail},
    'variants': {
        'product': {
            'small': thumbnail,
            'large': Transform(width=1280, format='webp'),
        },
    },
}

client.base_url is required. Set key and salt to your server’s hex-encoded credentials, or omit both if the server accepts unsigned URLs.

Serializer fields

Use ImgproxyURLField for one URL and ImgproxyVariantsField for a dictionary of named URLs. Both fields read the original image from source:

from rest_framework import serializers

from imgproxykit.integrations.drf import ImgproxyURLField, ImgproxyVariantsField


class ProductSerializer(serializers.Serializer[dict[str, str]]):
    """Return a thumbnail and named variants for a product image."""

    thumbnail = ImgproxyURLField(source='image', transform='thumbnail')
    images = ImgproxyVariantsField(source='image', variants='product')

transform='thumbnail' selects IMGPROXYKIT['transforms']['thumbnail']. variants='product' selects IMGPROXYKIT['variants']['product']. The response contains a thumbnail URL and an images dictionary with small and large URLs.

The same field declarations work in a ModelSerializer: use the model’s file field as source and include the generated fields in Meta.fields. Request context is not required, and URL generation makes no network requests.

Note

Both fields are read-only. Empty strings, None, and model file fields without an associated file produce null. Empty sources are not passed to the source resolver.

Inline transformations

Pass a Transform or a mapping of transformations directly instead of referring to Django settings by name:

from rest_framework import serializers

from imgproxykit import Transform
from imgproxykit.integrations.drf import ImgproxyURLField, ImgproxyVariantsField


class ProductSerializer(serializers.Serializer[dict[str, str]]):
    """Return a product image at explicitly configured sizes."""

    thumbnail = ImgproxyURLField(
        source='image',
        transform=Transform(width=160, height=160),
    )
    images = ImgproxyVariantsField(
        source='image',
        variants={
            'small': Transform(width=320),
            'large': Transform(width=1280),
        },
    )

Omit transform from ImgproxyURLField to generate a URL without processing options. ImgproxyVariantsField always requires variants.

File uploads

Use a standard DRF ImageField to accept uploads, alongside the generated fields used in the response:

image = serializers.ImageField(write_only=True, required=False)
thumbnail = ImgproxyURLField(source='image', transform='thumbnail')
images = ImgproxyVariantsField(source='image', variants='product')

In a ModelSerializer, include all three fields in Meta.fields. Configure an appropriate parser for the upload endpoint, as described in DRF’s file upload documentation.

Source resolution

Nonempty source strings and model file fields use the Django integration’s source resolver. By default, strings are passed unchanged and file fields use their storage URL. Relative URLs are not expanded using the request. See Django for relative media URLs and custom storage URIs.

Next steps