Client

A Client stores your imgproxy server’s public address and signing settings. Create it once and reuse it for different source images and transformations.

Configure server address

Pass the public address of your imgproxy server as the first argument. Include a path prefix if your server is exposed under one:

from imgproxykit import Client

# Include the path prefix where your imgproxy server is exposed.
client = Client('https://imgproxy.example.com/imgproxy/')

source_url = 'https://originals.example.com/photo.jpg'
imgproxy_url = client.url(source=source_url)

imgproxy_url starts with https://imgproxy.example.com/imgproxy/. The client preserves the path prefix and removes trailing slashes from the server address.

source_url identifies the original image that imgproxy will fetch. Pass a complete source URI understood by your server; it is encoded into the resulting URL, rather than resolved relative to the server address.

Sign URLs

Supply both key and salt when creating Client. Use the same hex-encoded values configured in your server’s IMGPROXY_KEY and IMGPROXY_SALT:

from imgproxykit import Client

client = Client(
    'https://imgproxy.example.com',
    # Replace with your imgproxy server's hex-encoded key and salt.
    key='736563726574',
    salt='73616c74',
)
source_url = 'https://originals.example.com/photo.jpg'

imgproxy_url = client.url(source=source_url)

imgproxy_url contains a signature covering the processing options and encoded source. The same source and options produce the same signature. The client also signs every URL generated by variants().

Warning

Keep the key and salt in your application on the server. Send only the generated URLs to browsers and other clients. Replace the example credentials above with your server’s values.

Use unsigned URLs

Omit both credentials to create a client that uses the unsafe marker:

from imgproxykit import Client

client = Client('https://imgproxy.example.com')

URLs generated by this client contain /unsafe/ in place of a signature. Your imgproxy server must accept unsigned requests for these URLs to work.

Customize the unsigned marker

Set unsigned_signature to use a different marker:

from imgproxykit import Client

client = Client(
    'https://imgproxy.example.com',
    unsigned_signature='public',
)
source_url = 'https://originals.example.com/photo.jpg'

imgproxy_url = client.url(source=source_url)

imgproxy_url contains /public/ in place of /unsafe/. If signature checking is enabled, the server must list this marker in IMGPROXY_TRUSTED_SIGNATURES. A trusted marker bypasses signature checking; anyone who knows it can construct URLs with different processing options.

Match server settings

The defaults work with imgproxy’s default signature size and processing arguments separator. If your server changes either setting, configure Client to match.

Signature size

The default signature uses the full 32-byte SHA-256 digest. For a server configured with IMGPROXY_SIGNATURE_SIZE=16, set signature_size=16:

client = Client(
    'https://imgproxy.example.com',
    key='736563726574',
    salt='73616c74',
    signature_size=16,
)
Full example
from imgproxykit import Client

client = Client(
    'https://imgproxy.example.com',
    key='736563726574',
    salt='73616c74',
    signature_size=16,
)
source_url = 'https://originals.example.com/photo.jpg'

imgproxy_url = client.url(source=source_url)

The signature contains 16 digest bytes before URL-safe Base64 encoding. signature_size counts bytes, rather than characters in the resulting URL.

Arguments separator

Processing arguments use : by default, as in resize:fill:300:200. For a server configured with IMGPROXY_ARGUMENTS_SEPARATOR=,, set arguments_separator=',':

client = Client(
    'https://imgproxy.example.com',
    arguments_separator=',',
)
Full example
from imgproxykit import Client, Transform
from imgproxykit.options import Resize

client = Client(
    'https://imgproxy.example.com',
    arguments_separator=',',
)
source_url = 'https://originals.example.com/photo.jpg'

imgproxy_url = client.url(
    source=source_url,
    transform=Transform(
        Resize(mode='fill', width=300, height=200),
        format='webp',
    ),
)

The resulting URL uses segments such as resize,fill,300,200. Options remain separated by /. The configured separator applies to all processing options, including preset references and the output format.

Next steps