Cloudinary conformance

This guide documents image_plug's conformance to the Cloudinary delivery URL grammar — what we implement, where we differ, and what we deliberately don't ship.

The reference is Cloudinary's published transformation reference. When this guide and Cloudinary's docs disagree, treat Cloudinary's docs as the contract and file an issue against image_plug.

URL forms

Provider configuration

plug Image.Plug,
  provider: {Image.Plug.Provider.Cloudinary,
             mount: "",
             account: "demo",
             strict?: true,
             signing: %{keys: [secret], required?: true}},
  source_resolver: ...

• :mount — path prefix to strip before treating the rest as a Cloudinary URL. Defaults to "" (root).

• :account — when set, asserts the URL's account segment matches this value (rejects mismatches with :malformed_url). When nil (default), any account segment is accepted and reported through the recogniser.

• :strict? — true (default) rejects unknown Cloudinary option keys with :unknown_option. false logs and ignores.

• :signing — nil or %{keys: [...], required?: bool}. Wire format matches Cloudinary's hosted SHA-256 signed URLs (32 url-safe-base64 characters).

Option-key conformance

Every option Cloudinary documents in the transformation reference. ✅ = full conformance. ⚠️ = partial / behavioural difference. ❌ = not implemented.

Sizing

Format / output

Effects

Geometry

Overlays

Misc

Behavioural differences

Multi-stage chained transforms collapse to one stage

Cloudinary lets you chain transforms with /: w_200,c_fill/e_blur:300/q_auto. Each stage runs as a separate transformation pass; later stages see the output of earlier ones. The canonical IR in v0.1 doesn't model multi-pass pipelines — all options compose into one Resize op, one Adjust op, etc.

The provider flattens the stages by joining them with , and processes them as a single set. For most useful transforms (resize + format + quality + a single effect) this is identical to Cloudinary. Recipes that genuinely require ordering (sharpen at original resolution → resize → sharpen at output resolution) lose information: only the second sharpen survives.

If you hit a real-world case where this matters, open an issue with the URL and the expected behaviour.

Canonical-string for signing

Cloudinary's HMAC payload is <transforms>/<source><api_secret> — secret appended to the canonical string (not used as the HMAC key). The result is hashed with SHA-256 (we ship SHA-256 only; SHA-1 is legacy) and truncated to 32 url-safe-base64 characters. We replicate this exactly. URLs signed by Cloudinary's hosted service verify against an image_plug deployment with the same secret, and vice-versa. No wire-level translation needed.

Account segment is required

Cloudinary URLs always carry an account segment (<host>/<account>/image/upload/...) even when self-hosted. The provider requires it structurally; configuring :account lets the provider reject mismatches with :malformed_url rather than silently routing them through.

q_auto doesn't auto-tune quality

Cloudinary's q_auto (and its variants q_auto:eco, q_auto:good, q_auto:best) selects an output quality based on image content analysis. The Image library doesn't expose a content-aware quality knob, so we leave the encoder default (85) in place and set compression: :fast. This produces sensible output but isn't byte-identical to Cloudinary's hosted result.

Conformance summary

Reporting gaps

Open an issue at the project's GitHub. Include the request URL, the expected behaviour per Cloudinary's docs (with a link), and the actual response.