URL Structure

imgFlux mirrors the URL layout of image cdn: every transformation is encoded inside the request path, and requests are authenticated via an HMAC signature. Source URLs can be provided either in plain text (with the plain/ prefix) or Base64-encoded format. This document details the anatomy of those URLs, explains how to sign them, and highlights development shortcuts.

Path anatomy

http(s)://<host>/<signature>/<processing_options>/plain/<percent-encoded-source>@<extension>
http(s)://<host>/<signature>/<processing_options>/<base64url-source>.<extension>

URL structure visualization

┌──────────────────────────────────────────────────────────────────────────┐
│                              URL Anatomy                                 │
└──────────────────────────────────────────────────────────────────────────┘

Plain format example:
┌───────────┬────────────────┬──────────────────────┬──────────────────────┐
│ https://  │ imgFlux.com/   │ Q7j8K...NpM/         │ ex:800x600/ │
│ Protocol  │ Host           │ HMAC Signature       │ Processing Options   │
└───────────┴────────────────┴──────────────────────┴──────────────────────┘
┌──────────────────────────────────────────────────────────────────────────┐
│ plain/https%3A%2F%2Fexample.com%2Fcat.jpg.webp                           │
│ Source URL (percent-encoded) + Output Format                             │
└──────────────────────────────────────────────────────────────────────────┘


Base64 format example:
┌───────────┬────────────────┬──────────────────────┬──────────────────────┐
│ https://  │ imgFlux.com/   │ Q7j8K...NpM/         │ trim:1024:0/   │
│ Protocol  │ Host           │ HMAC Signature       │ Processing Options   │
└───────────┴────────────────┴──────────────────────┴──────────────────────┘
┌──────────────────────────────────────────────────────────────────────────┐
│ aHR0cHM6Ly9leGFtcGxlLmNvbS9jYXQzLmpwZw.webp                              │
│ Base64URL-encoded source      + Output Format                            │
└──────────────────────────────────────────────────────────────────────────┘


Processing Options Chain:
┌─────────────────────────────────────────────────────────────────────────┐
│      800x600ex       / quality:85 / blur:2.5 / watermark:0.8:se         │
│  ─────┬────────────   ────┬─────   ────┬────   ──────────┬──────        │
│       │                   │            │                 │              │
│       ▼                   ▼            ▼                 ▼              │
│  Directive:args      Directive:arg  Directive:arg   Directive:args      │
└─────────────────────────────────────────────────────────────────────────┘

Segment	Description
`<signature>`	Base64 URL-safe, unpadded HMAC-SHA256 digest generated from the path. Use `unsafe` when unsigned URLs are permitted.
`<processing_options>`	Slash-separated list of directives (e.g., `800x600q85trim`). See Processing Options.
`plain/...`	Indicates the source URL is provided in plain text (percent-encoded if needed) and may include `@<extension>` to declare the output format.
`<base64url-source>`	The source URL encoded using URL-safe Base64 without padding (`=`). The output extension, if specified, is appended after a dot.

Choosing between `plain` and Base64

Source URLs can be provided in two formats:

Plain format (plain/ prefix): Use when the source URL contains only URL-safe characters and you want to specify the output format explicitly with @<extension>
Base64 format: Use when the source URL contains special characters, query parameters, or when you want to avoid potential encoding conflicts

Examples

Plain URL format with format conversion:

/<teamName>/1024x0trim/plain/https://example.com/cats/siamese.jpg.webp

Base64-encoded URL format:

/<teamName>/800x600ex/aHR0cHM6Ly9leGFtcGxlLmNvbS9jYXRzL3NpYW1lc2UuanBn.jpg

Note: aHR0cHM6Ly9leGFtcGxlLmNvbS9jYXRzL3NpYW1lc2UuanBn is the Base64URL encoding of https://example.com/cats/siamese.jpg

Plain URL with query parameters (requires Base64):

/<teamName>/800x0trim/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc_dj0xMjM.webp

Note: aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc_dj0xMjM is the Base64URL encoding of https://example.com/image.jpg?v=123

Generate Base64 URL-safe strings without padding (replace + with -, / with _, and remove trailing =).

Next steps

Explore available transformations in Processing Options.
Review the request lifecycle in Request Lifecycle.
If your application generates many URLs, encapsulate signing logic into a shared helper library to avoid drift.