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 an example and open the 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.

Pass an image URI as source and a Transform as transform to url():

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

client = Client('http://localhost:8080')  # (1)!
source_url = 'https://picsum.photos/id/237/1600/1200'

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

thumbnail_url = client.url(source=source_url, transform=thumbnail)  # (2)!
print(thumbnail_url)

Address of the local imgproxy container started above.
Generate a URL without making a network request. Imgproxy fetches and processes the source image when the generated URL is requested.

Show Output

http://localhost:8080/unsafe/resize:fill:300:300/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Use thumbnail_url in an image’s src attribute or an API response.

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

from imgproxykit import Client

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

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

Show Output

http://localhost:8080/unsafe/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Imgproxy applies its server defaults.

Shorten option names¶

Set use_short_options=True to use aliases such as w and q:

from imgproxykit import Client, Transform

client = Client('http://localhost:8080', use_short_options=True)  # (1)!
source_url = 'https://picsum.photos/id/237/1600/1200'

image_url = client.url(
    source=source_url,
    transform=Transform(width=300, quality=85),
)
print(image_url)

Use short aliases where available. Options without a short alias keep their full names.

Show Output

http://localhost:8080/unsafe/w:300/q:85/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Changing this setting changes URL paths and their signatures.

Encode the source URL¶

By default, source URLs use URL-safe Base64. Set source_encoding='plain' to use percent-encoding with imgproxy’s /plain/ marker:

from imgproxykit import Client, Transform

client = Client('http://localhost:8080', source_encoding='plain')  # (1)!
source_url = 'https://picsum.photos/id/237/1600/1200'  # (2)!

image_url = client.url(
    source=source_url,
    transform=Transform(width=300, format='webp'),
)
print(image_url)

Select plain encoding for all URLs generated by this client.
Pass the original source URI. The client percent-encodes it for you; do not encode it before passing it to url().

Show Output

http://localhost:8080/unsafe/width:300/format:webp/plain/https%3A%2F%2Fpicsum.photos%2Fid%2F237%2F1600%2F1200

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',
    key='736563726574',  # (1)!
    salt='73616c74',
)
source_url = 'https://picsum.photos/id/237/1600/1200'

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

Example hex-encoded credentials matching the container above. Replace both key and salt with your server’s values in your application.

Show Output

http://localhost:8081/bkt7Ya6TIVVTNH7Py-OPS1xzpIuvZTXBFFWLGiQa56I/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

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.

Next steps¶

Continue with Transform to define and reuse image transformations. To generate several versions of one image, see Variants. See the Client API reference for all configuration options.