Client¶

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

Tip

Start this container to try examples. Run and open a printed URL in your browser.

docker run -d --rm \
  --name imgproxy-guide \
  -p 127.0.0.1:8080:8080 \
  -e 'IMGPROXY_ALLOW_SECURITY_OPTIONS=true' \
  -e 'IMGPROXY_PRESETS=thumbnail=resize:fill:300:300,small=resize:fill:96:96' \
  ghcr.io/imgproxy/imgproxy:v4.0.0

This server accepts unsigned URLs and enables the presets and security options used in the guide.

Build a URL¶

Create a client with your imgproxy server’s address. Without signing credentials, it generates unsigned URLs containing /unsafe/; the server must accept unsigned requests.

Call url() with the original image’s URI as source. The source must be accessible to imgproxy. Pass a Transform through transform to include processing options:

from imgproxykit import Client, Transform
from imgproxykit.options import Resize

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

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

# Build the URL; imgproxy processes the image when the URL is requested.
thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

thumbnail_url is a string ready for an image’s src attribute or an API response. URL generation makes no network requests; imgproxy fetches and processes the original when the generated URL is requested.

To generate a URL without explicit processing options, omit transform:

image_url = client.url(source=source_url)
print(image_url)

Imgproxy applies its server defaults.

Sign URLs¶

Tip

Start this container to try the signing example on port 8081. Run the example and open the printed URL in your browser.

docker run -d --rm \
  --name imgproxy-guide-signed \
  -p 127.0.0.1:8081:8080 \
  -e 'IMGPROXY_KEY=736563726574' \
  -e 'IMGPROXY_SALT=73616c74' \
  ghcr.io/imgproxy/imgproxy:v4.0.0

This server checks URL signatures using the key and salt from the example below.

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(
    'http://localhost:8081',
    # Replace with your imgproxy server's hex-encoded key and salt.
    key='736563726574',
    salt='73616c74',
)
source_url = 'https://picsum.photos/id/237/1600/1200'

imgproxy_url = client.url(source=source_url)

print(imgproxy_url)

This client signs URLs generated by both url() and variants().

Warning

Keep the key and salt in your application on the server. Send only the generated URLs to browsers and other clients. Use your own credentials when connecting to a production server.

Generate several URLs¶

variants() accepts a mapping of names to complete transformations and returns a dictionary of URLs for one source. Every URL uses this client’s configuration. See Variants for defining, reusing, and typing these mappings.

Tip

Keep the server on port 8080 running for the remaining chapters. When finished, stop it:

docker stop imgproxy-guide

If you also started the signing example, stop that container:

docker stop imgproxy-guide-signed

Next steps¶

Continue with Transform to define and reuse image transformations. See the Client API reference for all configuration options.