Developer Reference v2.0

Universal URL Syntax & Transforms

ImageEngine routes, optimizes, and edge-caches any asset on-the-fly using a clean, path-based hierarchical URL pattern.

Active Edge CDN Endpoints

You can use either of our official edge hostnames interchangeably:

Primary Endpoint

https://img.grisma.info.np

Ecosystem Endpoint

https://img.topnepali.com

1. Universal URL Format

Every asset request follows the multi-tenant namespaced schema:

https://img.grisma.info.np/{tenant_id}/{subdomain}/{path/to/asset}-{origExt}.{targetExt}

{tenant_id}

The verified organization identifier mapped to your root domain (e.g. acme).

{subdomain}

The specific app or microservice (e.g. store, blog). Use main or @ for root.

{path}-{origExt}

Exact origin path and source extension (e.g. products/sneaker-jpg, og/banner-svg).

.{targetExt}

Desired output format: .webp, .avif, .png, or .jpg.

⚡ Deterministic Zero-Probing Architecture: By specifying the source extension with a hyphen before the target format (logo-png.webp), ImageEngine reconstructs the exact origin URL (logo.png) in a single HTTP request with zero ambiguity and zero trial-and-error checks.

🌐 Universal Host-Agnostic Routing: Regardless of where ImageEngine is hosted, routing is strictly driven by the URL path: /{tenant}/{path}-{origExt}.{targetExt} for the root domain (e.g. /tn/abc-jpg.webp) or /{tenant}/{subdomain}/{path}-{origExt}.{targetExt} for subdomains (e.g. /tn/blog/logo-png.jpg).

2. Generic Real-World Examples

E-Commerce Product Image

WebP 800px

Fetches from origin https://store.acme.com/products/sneaker.jpg, compresses, and caches globally:

https://img.grisma.info.np/acme/store/products/sneaker-jpg.webp?w=800

User Profile Avatar (Face-Aware)

Avatar Mode

Applies smart top/face-focused cropping and outputs a clean square WebP profile thumbnail:

https://img.grisma.info.np/acme/app/users/avatars/john-doe-jpg.webp?avatar=true&w=256

OpenGraph / Social Media Card

SVG to WebP

Dynamically renders an origin vector SVG (e.g. https://blog.acme.com/og/article-1024.svg) to WebP:

https://img.grisma.info.np/acme/blog/og/article-1024-svg.webp

3. Query Parameters Reference

By default, ImageEngine preserves 100% of the original image dimensions and aspect ratio. Only apply parameters when explicit transformations are desired.

Original Dimensions Preserved

Parameter	Aliases	Type	Default	Description
w	width	integer	original	Target width in pixels. Original aspect ratio is preserved unless `h` is also passed.
h	height	integer	original	Target height in pixels. Original aspect ratio is preserved unless `w` is also passed.
q	quality	1 – 100	85	Compression quality factor. Higher values preserve maximum detail, lower values save more bandwidth.
format	—	string	webp	Output image codec. Values: `webp`, `png`, `jpg`, `avif`.
fit	—	string	cover	Resize mode when both `w` and `h` are provided: `cover`, `contain`, `fill`, `inside`, `outside`.
position	—	string	center	Crop anchor for `cover` fit: `top`, `center`, `bottom`, `left`, `right`, `entropy`, `attention`.
avatar	—	boolean	false	Applies face-focused top-anchored square crop (defaults to 256x256 WebP or custom `w`).
blur	—	0.3 – 1000	none	Gaussian blur sigma radius. Ideal for generating ultra-low-bandwidth progressive blur placeholders (e.g. `?w=40&blur=5`).
sharpen	—	boolean	false	Applies an adaptive unsharp mask sharpening filter for crystal-clear high-DPI displays.

4. Edge Cache Headers

Every optimized asset response contains immutable caching directives honored by modern browsers and Cloudflare's 330+ edge data centers:

Cache-Control: public, max-age=31536000, s-maxage=31536000, immutable
CDN-Cache-Control: public, max-age=31536000, immutable
CF-Cache-Status: HIT
X-Render-Engine: sharp-raster (or sharp-svg)

Integrate in 60 Seconds

Check out our zero-touch drop-in client script. It automatically detects and optimizes all images on your website with zero manual URL rewrites.

⚡ View Drop-in Script Integration →