Manipulation API documentation

Quick start

Make your first delivery request.

Every delivery URL begins with the project delivery key, identifies a source, and adds zero or more manipulation parameters. The response body is the final image—not JSON.

GET200 · image/webp

https://imagario.web.app/image/v1/project-key/assets/hero-chair?sw=1200&sh=800&fit=cover&g=attention&of=webp&c=86

The project’s delivery key is separate from its editable slug. Originals stay private; only validated delivery routes can read them.

Image sources

Use a stored asset or a remote URL.

Uploaded originals are addressed by their editable asset ID. Remote originals use a Base64URL-encoded source URL in the path—this is the remote URL encoded as text, not image bytes.

source routesHTTPS

# Project asset
/project-key/assets/asset-id?of=webp

# URL-safe Base64 encoded https://example.com/photo.jpg
/project-key/remote/aHR0cHM6Ly9leGFtcGxlLmNvbS9waG90by5qcGc?sw=900

A fetched remote original is kept privately for reuse. If it is not referenced for 90 days, it becomes eligible for cleanup. A later request can fetch it again.

Parameter reference

Compose a validated pipeline.

Parameters can appear in any order. Imagario normalizes them into a canonical operation sequence before generating the cache key.

KeyAccepted valueBehavior

orauto | none | -360…360

Orientation. Apply EXIF orientation automatically, ignore EXIF orientation, or rotate by an angle. Default: auto for non-empty pipelines.

flipx | y | xy

Mirror. Mirror the image across the x axis, y axis, or both axes.

sp1…400

Scale percent. Scale both dimensions proportionally from 1% through 400%.

sw1…8192

Target width. Set a target width in pixels. With no height, the aspect ratio is preserved.

sh1…8192

Target height. Set a target height in pixels. With no width, the aspect ratio is preserved.

Fit mode. Choose how the source is resized or cropped into the target dimensions. Default: fit.

gposition | entropy | attention

Gravity. Anchor a crop to a compass point or use entropy/attention-based positioning. Default: center.

bgtransparent | hex color

Background. Set the background color used by contain-mode padding. Default: transparent.

no_up1 | true

Prevent enlargement. Prevent a resize from enlarging a source that is already smaller than the target. Default: false.

ofjpeg | png | webp

Output format. Encode the delivered image as JPEG, PNG, or WebP. Default: source.

c1…100

Compression. Choose fidelity from 1 (maximum compression) to 100 (no lossy compression requested). Default: 82.

baseline1 | true

Baseline encoding. Disable progressive encoding when the target format supports it. Default: false.

Compression is intentionally intuitive: c=100 requests maximum fidelity and no lossy compression; c=1 requests maximum compression. Encoders translate that policy appropriately for each format.

The v1 engine caps work at 8192 pixels per axis, 40 megapixels, and 25 MiB of encoded output. Oversized requests fail before a derivative is retained.

Resize behavior

Choose how the source meets its bounds.

Use sw or sh alone for proportional scaling, both for a bounded resize, or sp for a percentage. Pixel dimensions and percentage scale cannot be mixed.

fit=fit

Fit inside both bounds while preserving aspect ratio; no crop or padding.

fit=fill

Fill the exact dimensions by stretching when the source ratio differs.

fit=cover

Fill both bounds and crop overflow using the selected gravity.

fit=contain

Fit inside both bounds and pad the remaining area with the background.

fit=inside

Resize as large as possible while remaining within the bounds.

fit=outside

Resize as small as possible while covering both bounds.

examplesgeometry

# 50% of source dimensions
sp=50

# 900px wide, proportional height
sw=900

# Exact 900×900 frame with smart crop
sw=900&sh=900&fit=cover&g=attention

Gravity & orientation

Keep the important region in frame.

For crops, gravity accepts compass positions from north through northwest, plus center, entropy, and attention. Entropy favors the busiest region; attention favors visually salient areas.

orientation-and-crop.txtpipeline

or=auto&flip=x&sw=1200&sh=800&fit=cover&g=northeast

Use or=auto to apply EXIF orientation before geometry, an angle from −360 through 360 to rotate explicitly, and flip=x, flip=y, or flip=xy to mirror.

Named manipulations

Publish the recipe, then call it by name.

Named manipulations are project-specific and versioned. They keep application URLs stable while your team manages the underlying recipe in one place.

named requestGET 200

https://imagario.web.app/image/v1/project-key/assets/hero-chair?m=product-card

Deterministic delivery

Process once. Reuse the exact derivative.

The same source revision, canonical manipulation, engine version, and output policy always resolve to the same derivative key.

01Resolve sourceAuthorize asset or safely fetch remote.

02CanonicalizeValidate and order operation handlers.

03Resolve cacheReturn an existing derivative if present.

04Process & storeCreate once, record, and serve the image.

Transparent metering

Three independent usage dimensions.

Manipulation uses a fixed credit rate when work is performed. Private storage accrues daily at its per-GB rate. Delivered bytes consume bandwidth credits at a separate per-GB rate. Every ledger event uses the pricing version effective at that moment.

Cache hits avoid repeated manipulation cost, but the bytes delivered still count toward bandwidth. Storage continues to accrue while an original or derivative is retained.

Create a project

Image delivery that reads like a sentence.