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.

Watermarks

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

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.

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 are delivered from the edge in under 200ms. 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

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 (this is completely distinct from the Core API api.picsha.ai/v1/jobs endpoints used for heavy transcoding workflows).

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

Because delivery URLs allow dynamic parameter injection by default, public-facing applications run the risk of billing abuse and Lambda exhaustion. If a malicious user discovers your public image URLs, they could intentionally append an infinite permutation of query strings (e.g. ?w=1, ?w=2) or generative parameters (?mimi=expensive+prompt) to artificially drive up your usage and bypass the CDN cache.

To securely lock down your assets, you should 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 403 Forbidden any transformation URL that modifies dimensions, formats, or applies generative AI (like mimi or bg_rem) 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.
3. Protected Generative Billing: This ensures you only pay for mimi operations or background operations that your system explicitly authorized, effectively closing the open billing faucet.