Django REST Framework

Django REST Framework (DRF) is a toolkit for building Web APIs with Django. Use imgproxykit’s serializer fields to return image URLs and named variants, with transformations from Django settings or defined directly on the fields.

Explore the DRF quickstart and the project on GitHub.

Installation

In your DRF project, install imgproxykit with Django REST Framework support:

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. The client, transformations, variant sets, and source resolver are shared 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': {  # (1)!
        'base_url': 'https://imgproxy.example.com',
        'key': '736563726574',  # (2)!
        'salt': '73616c74',
    },
    'transforms': {'thumbnail': thumbnail},  # (3)!
    'variants': {  # (4)!
        'product': {
            'small': thumbnail,
            'large': Transform(width=1280, format='webp'),
        },
    },
}

  1. Configure the shared client. base_url is required.

  2. Use your server’s hex-encoded key and salt, or omit both if the server accepts unsigned URLs.

  3. Optional named transformations shared with the Django integration.

  4. Optional named sets of transformations for generating variants.

Serializer fields

Use ImgproxyURLField for one URL and ImgproxyVariantsField for named variants. Set source to the original image field:

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(  # (1)!
        source='image',
        transform='thumbnail',
    )
    images = ImgproxyVariantsField(  # (2)!
        source='image',
        variants='product',
    )

  1. Use the named transformation from IMGPROXYKIT['transforms']['thumbnail'].

  2. Use the named variant set from IMGPROXYKIT['variants']['product'].

For a ModelSerializer, use the model’s file field as source and include the generated fields in Meta.fields. Request context is not required.

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),  # (1)!
    )
    images = ImgproxyVariantsField(
        source='image',
        variants={  # (2)!
            'small': Transform(width=320),
            'large': Transform(width=1280),
        },
    )

  1. Pass a Transform directly instead of a configured name.

  2. Map variant names to their transformations.

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:

from rest_framework import serializers

from imgproxykit.integrations.drf import (
    ImgproxyURLField,
    ImgproxyVariantsField,
)

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

  1. Accept uploads with a standard DRF field. The generated fields remain read-only and appear in the response.

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 sources use the Django source resolver. Strings are passed unchanged; file fields use .url. Relative URLs are not expanded using the request. See Django to configure source resolution.

Next steps