Image Delivery

GET /api/v1/{spaceName}/pictures/{mediaId}

The endpoint is public, so it can be used directly in src and srcset without an API key. Flexim keeps raster uploads byte-for-byte and builds requested variants only from the stored master. SVG uploads remain vector files, but Flexim sanitizes them into a secure-static master before storage.

With no w, q, fm, or auto parameter, the endpoint always redirects to the stored master: byte-for-byte for raster uploads, or the secure-static vector for SVG uploads.

Query parameters

For example:

GET /api/v1/main/pictures/697cb45ff5d03dbe82112b84?w=1200&q=90&auto=format

Supported widths

Flexim uses this global grid:

64, 128, 236, 500, 750, 1000, 1600, 2560, 4096, 6400, 8192

You may request any whole number from 1 to 8192. Flexim rounds it up: w=1200 becomes 1600, w=237 becomes 500, and w=1 becomes 64. The actual result is returned in X-Flexim-Width.

Images are never upscaled. If the master is 1200px wide, both w=1200 and w=1600 resolve to the 1200px master width. Invalid, fractional, zero, negative, and above-8192 widths return 400.

Format negotiation

Format negotiation is opt-in with auto=format:

1. AVIF when Accept includes image/avif
2. WebP when Accept includes image/webp
3. the master's format

Only negotiated responses include Vary: Accept. Without auto=format, Accept does not change the result. Use fm for a fixed format; passing both fm and auto returns 400.

PNG and GIF encoders do not use this quality setting, so requests with different q values share the same cached result for those formats. GIF and animated WebP keep all frames and are always built in the background. Converting a known animation to JPEG, PNG, or AVIF returns 400 rather than silently returning only its first frame. For older media without stored frame metadata, the worker inspects the real file and falls back to the master if a conversion would lose frames. Animated AVIF is returned as its master when a supported animated conversion is not available.

SVG masters

SVG uploads are stored as secure-static vectors: scripts, event handlers, external references, embedded SVG documents, and animation are removed before the master is written. Static paths, shapes, gradients, local fragment references, and small embedded raster images remain supported. Documents with DTDs, entities, invalid XML, or excessive size and complexity are rejected with 400.

For an SVG master, a delivery request without fm preserves the vector master even when w or q is present. Set fm=jpeg|png|webp|avif to request a raster derivative; the image worker applies the requested width and other supported parameters. auto=format rasterizes to AVIF or WebP only when the matching format is accepted, and otherwise preserves the SVG master.

Cold and cached responses

The endpoint responds with a 302 redirect:

• A cached variant redirects to its immutable CDN URL.
• A light cold variant may be built during a wait of up to 250 ms; otherwise that request receives the master while the worker continues.
• A heavy cold variant is queued and immediately redirects to the master with Cache-Control: public, max-age=30 and X-Flexim-Transform: queued.
• A source above 40 MB, above 80 megapixels across all frames, or above 100 animation frames is not transformed and redirects to the master.
• Memory-intensive outputs are checked before encoding. All formats are limited to 32 megapixels of output; AVIF and alpha-preserving WebP use a stricter 16 megapixels limit. Larger combinations redirect to the master instead of risking a worker restart. The full width ladder through 8192px remains available when the source aspect ratio stays within those limits.

The first visitor to a heavy cold variant therefore receives the master. Later visitors receive the optimized variant after the background worker finishes it. Repeated requests for the same cold variant do not create duplicate work.

The worker runs one transform at a time and keeps short, bounded light and heavy queues. If it is unavailable, timed out, or full, Flexim still redirects to the master instead of returning 429.

Unique cold variants are limited to 600 per client IP and 6000 per space in each 10-minute window. Cache hits and repeats of a key that is already active or queued do not consume these budgets. When a budget is exhausted, the endpoint still returns 302 to the master and sets X-Flexim-Transform: limited.

Separately, an emergency ceiling protects the public endpoint itself from raw request floods before they reach the database or storage: 6000 image requests per minute per client IP. Exceeding only this high request ceiling returns 429 with code IMAGE_DELIVERY_RATE_LIMITED. It is independent of worker admission, so a full worker queue, an expensive transform, or repeated cold variants still fall back to the master with 302.

Derived files are infrastructure cache, not space storage usage. They expire after 30 days, and each master version keeps at most 192 variants.

Response headers

Invalid parameters return 400, an unknown or deleted media ID returns 404, emergency request-flood protection may return 429, and successful delivery—including worker overload fallback—returns 302.

Legacy formats

Existing direct CDN links continue to work. Media objects also keep the same four fields:

New formats.* values are exposed only when Adaptive Loading is enabled and point to this endpoint. When Adaptive Loading is disabled, use the master url or construct an Image Delivery URL directly. For a smaller master, preset dimensions are reduced to the master size; they never upscale it.

New preset URLs use the space's current canonical name. Existing preset URLs that contain the older tenant ID form remain valid.

The Media setting selects the default quality placed in these links. Supported settings are 80, 90, 95, and 100; turning compression off selects 100. This never changes the stored master.