Image Transformations

Picsha AI's delivery pipeline relies on ultra-fast runtime transformations. You never need to pre-generate crops or thumbnails—simply request the exact dimensions you need, and the Edge cache will cache the resultant image for 1 year (31,536,000 seconds).

The Render Endpoint

The global edge rendering endpoint is: GET https://cdn.picsha.ai/render/:assetId

(Note: The CDN sits directly in front of the API. You may also see routes like GET /v1/assets/:assetId/render in our examples—both URL shapes are valid and route to the exact same transformation engine.)

SEO URL Aliasing

If you are building public-facing websites, you can leverage our automated AI-driven SEO endpoints. Instead of using /render, you can use /seo/ followed by the generated URL string. This endpoint functions identically to /render (accepting all the same parameters) but provides keyword-rich semantic URLs for web crawlers.

GET https://cdn.picsha.ai/seo/:assetId/:seoUrlString

Standard Parameters

Smart Cropping

One of our flagship features is AI-driven smart cropping! If you request fit=cover alongside a bizarre aspect ratio (like w=300&h=900), Picsha's AI will detect the subject of the image (or human faces) and automatically pivot the crop window (pos=entropy or pos=attention) to guarantee the subject is perfectly centered.

Edge Trim (trim=auto)

Scans, photos-of-photos, and some AI restorations often arrive with a near-uniform border — white scanner margins, mat board, or model-generated padding. Add trim=auto to shave it off at render time:

?w=2048&h=2048&fit=cover&trim=auto

• Opt-in and conservative. The detector samples the edge color and tolerates JPEG noise, but if trimming would remove more than 30% of either dimension, the trim is rejected wholesale and the image is served untrimmed — so legitimately flat edges (skies, snow, studio backgrounds) are never eaten.
• Derivative-cache friendly. On generative (MIMI) renders, trim=auto derives from the cached clean base exactly like a watermark overlay does: the base render stays untrimmed and shared, no generation is re-run or re-billed, and a watermarked preview and its clean unlock trim identically. Trim is applied before watermark tiling, so tiled marks repeat across the trimmed image, not the padded canvas.

Watermarks

You can seamlessly blend other asset URLs over your base image. ?wm=444e8400-e29b-41d4-a716-446655440000&wm_pos=southeast

Control the size and strength of the mark with wm_scale (a fraction of the output width) and wm_opacity: ?wm=444e8400-e29b-41d4-a716-446655440000&wm_pos=southeast&wm_scale=0.25&wm_opacity=0.5

Tiled Watermarks (crop-proof)

A single corner logo can be cropped out in seconds. For real content protection — for example, showing a free preview that converts into a paid clean download — use wm_mode=tiled: a rotated wordmark (or your logo) repeats across the entire image.

?wm_mode=tiled&wm_text=YOURBRAND&wm_opacity=0.35&wm_density=4&wm_rot=-30

• wm_text repeats a text wordmark — no watermark asset required. Alternatively pass wm=<assetId> (without wm_text) to tile your logo image.
• wm_density sets how many tile columns span the width (higher = smaller, denser marks), wm_rot the diagonal angle, and wm_opacity / wm_color the look. The defaults (0.35 opacity, density 4, -30°) are tuned to be unmistakable without ruining the preview.

Watermarks & the Derivative Cache (free clean unlock)

Watermarks, text, and overlays are composited as derivatives of the cached base render — they never re-run or re-bill a generative job. Render a MIMI image with a watermark, then request the identical URL without the watermark parameters (or vice versa): the second request reuses the cached base, bills no new generation, and returns an image pixel-identical to the first — just without the mark.

This makes the classic preview-to-purchase flow trivial:

1. Preview (unpaid user): sign and serve ?mimi=...&wm_mode=tiled&wm_text=YOURBRAND&sig=...
2. Unlock (after payment): sign and serve the same URL minus the wm_* parameters — optionally adding upscale=4k for the free preview-faithful 4K export, and exp=<unix seconds> to make the unlock link short-lived.

Both URLs resolve to the same billed-once base render, so the customer receives exactly the image they previewed. Keep every non-watermark parameter identical between the preview and unlock URLs — a different w/h is a different render. And because the signature covers the entire query, a user cannot strip the watermark parameters from a signed preview URL: any change breaks sig, and the request is rejected.

Background Operations (Background Ops)

Picsha provides lightning-fast background extraction and replacement tools built directly into the delivery pipeline. These are specialized pipeline operations distinct from MIMI's natural language editing.

Background Removal

To effortlessly strip the background from any subject (such as a person, product, or car), simply pass ?bg_rem=true to your Render endpoint!

GET /v1/assets/:assetId/render?bg_rem=true

How it stays fast: Picsha computes the subject cutout once per unique image, not once per render. If the asset was ingested with "remove_background": true in its upload config, the alpha cutout is already stored before your first render request — extraction is instant. Otherwise, the first bg_rem render generates the cutout and persists it. Either way, every subsequent request — at any size, format, or background — reuses the stored cutout with zero ML inference, and the rendered result is cached at the edge for 1 year. Content-identical files share one cutout automatically (deduplicated by pixel hash), so re-uploads never pay twice.

Because bg_rem=true can trigger AI cutout generation, it follows the generative authorization rule: call it with your Bearer key server-side, or sign the URL via sign-delivery for public embeds (see Security). Scene compositing with a pre-existing cutout via bg_asset alone remains publicly deliverable.

Background Replacement

Instead of simply removing the background, you can instantly replace it with a perfectly matched solid hex color.

GET /v1/assets/:assetId/render?bg=FF0000

This query effortlessly extracts the subject and blends it seamlessly onto a brilliant red background.

Background Compositing (Scenes)

For full contextual personalization, replace the background with a pre-rendered scene from your org's Backgrounds Library using bg_asset:

GET /v1/assets/:assetId/render?w=800&h=800&bg_asset=59a5b169-b504-45ee-96c3-c4822612aa9d

The subject cutout is layered over the stored scene as a pure-CPU composite — no generative model in the request path. Cold composites complete in a few seconds; cached composites return in under a second, served as immutable objects from the CDN edge. This is the recommended pattern for e-commerce personalization at scale: register one scene per context (weather, region, season), and every product in the catalog can be composited against it on demand.

Magic Image Manipulation Interface (MIMI)

You can provide freeform natural language instructions directly to the API to perform complex edits, color grading, and generative augmentations in one shot using our signature MIMI generative AI capability.

GET /v1/assets/:assetId/render?mimi=make it look like a moody cinematic shot

Authorization required. MIMI and all other billed generative parameters (mimi, mimi_bg, gen_rem, gen_fill, gen_mask, bg_rem=true) must be either called with your Authorization: Bearer API key (server-side — works unchanged, the engine signs its own CDN redirect) or carry a ?sig= signature minted via POST /assets/{id}/sign-delivery (for URLs embedded in public pages). Anonymous generative requests are rejected with 401 before any generation runs. Plain transforms remain publicly deliverable, and the async status endpoint (cdn.picsha.ai/render/status/:jobId) needs no auth — the jobId is an opaque handle. See Security below.

Quality Tiers & Sizing (mimi_mode)

MIMI is engineered to support ultra-high-definition professional assets. Depending on your needs, you can choose between three quality tiers via the mimi_mode parameter:

• MIMI Lite (mimi_mode=lite): Uses a fast generative model to produce a 1K resolution edit. This is ideal for rapid previews and real-time personalization. Typical latency is ~11–14 seconds.
• 2K Standard (mimi_mode=standard, the default): The default tier for most generative edits, rendered at 2K by our premium generative model — a perfect balance of quality and speed. Typical latency is ~25–29 seconds.
• Native 4K (mimi_mode=4k): The premium generative model generates the image natively at 4K for maximum fidelity. Typical latency is ~30–33 seconds.

Native 4K vs. free export upscale. These are two different things:

• mimi_mode=4k regenerates the edit at native 4K. It delivers the highest fidelity, but because it is a fresh generation, the image may differ from a 2K render of the same prompt.
• upscale=4k upscales the identical 2K render — same image as your 2K preview, just more pixels — and it is completely free. (upscale=2k is likewise available on Lite renders; upscaling is one tier up only.) The upscale pass takes ~4 seconds when the 2K base render is already cached (~30 seconds cold).

For preview-then-export workflows — validate the 2K preview, then download a high-resolution copy of exactly that image — always use upscale=4k.

(Note: the legacy mimi4k, mimi_4k, and mimi_lite boolean parameters have been removed and are no longer accepted — use mimi_mode and upscale instead.)

Generative Background Swap (mimi_bg)

For background replacement that goes beyond stored scenes, pass a natural language prompt via mimi_bg. The subject cutout is preserved pixel-exact and a brand-new background is generated from your prompt and composited behind it:

GET /v1/assets/:assetId/render?mimi_bg=misty alpine lake at golden hour

mimi_bg can be used on its own or combined with mimi (each is a separate generative operation).

Asynchronous Processing & Polling

When making heavy generative requests via MIMI (or when processing video formats), you can offload the processing to our background workers instead of holding the HTTP connection open. To do this, simply append &async=true to your render URL.

When using asynchronous processing, the CDN responds immediately with a JSON payload instead of an image binary:

• If the job is new or still processing, you receive an HTTP 202:

  { "status": "processing", "jobId": "f78a3..." }
  

• If the job has already completed and is cached, you receive an HTTP 200:

  { "status": "completed", "url": "https://cdn.picsha.ai/mimi-jobs/f78a3...webp" }
  

Polling for Status: The CDN delivery pipeline maintains its own ultra-fast edge polling endpoint. It is the only polling endpoint you need for generative renders — ingest and transcode completion is signalled by the asset.processed webhook instead.

GET https://cdn.picsha.ai/render/status/:jobId

It will return { "status": "processing" } until the job finishes, at which point it returns the completion JSON with the delivery URL. If a failure occurs, it returns { "status": "failed", "error": "Rendering failed or was cancelled" }.

Robustness & Best Practices:

• Status Synonyms: Our SDKs tolerate "pending" and "processing" interchangeably, as well as "complete" and "completed".
• Polling Interval: We recommend starting with a 2-3 second polling interval and applying an exponential backoff.
• TTL (Validity): The edge cache is immutable. The returned jobId and the final url remain valid for 1 year.

💡 Generative Billing & Performance

To keep pricing strictly pay-as-you-go and completely friction-free, Picsha employs single-stage flat-rate billing for all generative edits using MIMI — exactly one billing event per job, at the rate of the tier you chose:

[!NOTE] Standard background operations (?bg_rem=true, ?bg=..., and ?bg_asset=...) are not billed at generative rates. Cutout generation is billed once per unique image (bg_removal) — at ingest if you set "remove_background": true, or lazily on the first background render. All subsequent background renders and scene composites reuse the stored cutout at standard render rates and are cached at the edge.

• MIMI Lite Job: For ultra-fast, real-time personalization, mimi_mode=lite invokes a fast generative model that renders your edit at 1K resolution, billed at a flat rate of 6.0¢ (mimilite_job). (Note: Lite is a faster generation model, not an upscaler.)
• Standard MIMI Job: Every standard generative request (by passing ?mimi=...) is billed at a flat rate of 16.0¢ (mimi_job). This includes your 2K render for real-time validation in the console playground, plus a free preview-faithful 4K export upscale (upscale=4k) — download exactly the image you previewed, at 4K, at no additional charge.
• Native 4K Job: mimi_mode=4k regenerates at native 4K for maximum fidelity, billed at a flat rate of 32.0¢ (mimi4k_job).
• Background Swap Job: mimi_bg bills 16.0¢ (mimi_bg_job) once; if combined with mimi, both events bill (two generative operations).

You are billed exactly once per generative edit from your very first usage (0 monthly free units). The upscale parameter never bills. Downstream requests that hit the CDN cache directly (e.g., subsequent previews or downloads of a previously generated asset) are completely free, incurring only standard edge bandwidth charges — identical request configurations return from the derivative cache in under 1 second without billing a new generation!

Generate New Images (Text-to-Image)

MIMI can also create images from scratch. Send a JSON body to the Core API:

POST https://api.picsha.ai/v1/assets/generate

{
  "prompt": "a foggy pine forest at dawn",
  "aspect_ratio": "16:9",
  "quality": "standard"
}

• aspect_ratio (optional): one of 1:1, 3:4, 4:3, 9:16, 16:9, 2:3, 3:2, 4:5, 5:4. Default 1:1.
• quality (optional): lite | standard | 4k. Default standard.

The endpoint responds 201 { "assetId": "...", "url": "..." }. The generated image is ingested as a normal asset — analysis, DAM organization, renders, and further MIMI edits all work on it. Billing matches the corresponding MIMI mode price (6.0¢ / 16.0¢ / 32.0¢).

Security & Strict Transformations

Generative protection is always on. Any delivery URL carrying a billed generative parameter (mimi, mimi_bg, gen_rem, gen_fill, gen_mask, bg_rem=true) is rejected with 401 — at the API and at the CDN edge — unless it is either an authenticated Bearer API call (tenant-scoped to your own assets; the engine signs its own CDN redirect automatically) or carries a valid ?sig= signature minted via POST /assets/{id}/sign-delivery. Nobody who discovers an asset ID can burn paid generations against your account. This baseline cannot be disabled.

Short-lived signed URLs (exp). To give any signed URL an expiry, include an exp parameter (unix seconds) in the query you sign. The CDN edge rejects the URL after that time — and because exp sits inside the signed payload, it cannot be stripped or extended without invalidating the signature. Recommended for paid-unlock links and other time-boxed deliveries.

Plain transformation URLs, however, still allow dynamic parameter injection by default — a malicious user who discovers your public image URLs could append an endless permutation of query strings (e.g. ?w=1, ?w=2) to drive up bandwidth usage and bypass the CDN cache. To lock these down too, enable Strict Transformations in your organization's security settings.

When Strict Transformations are enabled:

1. Dynamic Parameter Rejection: The Picsha CDN edge will strictly reject any transformation URL that modifies dimensions, formats, or applies generative AI unless it includes a cryptographically valid ?sig= signature.
2. Pre-Authorized Permutations: Your backend uses the POST /assets/{id}/sign-delivery endpoint to pre-authorize the exact parameter combination (e.g., w=500&mimi=add+sunglasses). If the user modifies any parameter in the URL, the signature breaks, and the CDN refuses the request. Sign the exact path form you will serve — API-form (/v1/assets/{id}/render) or CDN-form (/render/{id}, /seo/{id}/{seoUrlString}).
3. Protected Billing: This ensures you only pay for transformations that your system explicitly authorized, closing the bandwidth faucet as well as the generative one.