Image transformation

Resize, format, and quality options for image URLs, and when an image isn't transformed.

Add a query to a media image URL to resize it, convert its format, or adjust its quality. You don't need to reprocess the original file in the dashboard. Get the URL from the dashboard or the delivery API.

Match the display size

You can build the URL with the SDK's buildImageUrl. This example assumes blog has an image field eyecatch.

import { buildImageUrl } from "@genko-me/sdk";import { genko } from "@/lib/client";
const post = await genko.apis.blog.getOrNull("abcDEF123456");const imageUrl = post?.eyecatch?.url  ? buildImageUrl(post.eyecatch.url, { w: 800, format: "webp", q: 80 })  : null;

This function only builds the URL. It doesn't fetch the image. Pass the result to an img or similar on the display side. If the image field isn't defined, add it first and sync types with pull.

Parameters

Name	Value	If omitted
`w`	Integer from 1 to 2,000. Width in px	Not set
`h`	Integer from 1 to 2,000. Height in px	Not set
`q`	Integer from 1 to 100. Output quality	`80`
`format`	`webp`, `avif`, `jpeg`, `png`, `auto`	Keep the original format
`fit`	`cover`, `contain`, `inside`	`cover` if both width and height are set, otherwise `inside`

q applies to WebP, AVIF, and JPEG, and not to PNG. An integer out of range or an unknown value returns 400. buildImageUrl validates values too, and throws when building the URL if a value is invalid.

Settings by use

Use	Example	Result
Images in body text	`w=800`	Adjusts the width and keeps the ratio
List thumbnails	`w=640&h=360&fit=cover`	Fills the given frame and crops what overflows
Fit the whole image in a frame	`w=640&h=360&fit=contain`	Keeps the whole image, and adds margins if the ratios differ
Shrink to fit within a frame	`w=640&h=360&fit=inside`	Keeps the ratio, and the output can be smaller than the frame

Images are never enlarged beyond the original. The width and height you set aren't always the actual output size.

format=auto

If the Accept header includes image/webp, the image is served as WebP, and otherwise in its original format. It doesn't pick AVIF automatically. If you need AVIF, set format=avif.

A response that was actually converted by the automatic format carries Vary: Accept. This differs from when the original file is returned without conversion.

When an image isn't transformed

With no transformation parameters, the original file is returned.
If the original file is larger than 25 MB, the original file is returned.
For an animated image, omitting format returns the original file. If you set a format, only the first frame is converted.

The size you can upload and the size that can be transformed are different. An image that uploaded successfully isn't transformed if it's over 25 MB.

If you add transformation settings to a file other than JPEG, PNG, WebP, GIF, or AVIF, you get 415. Don't add transformation parameters when serving PDFs and similar files.

Caching and replacement

Responses are served with Cache-Control: public, max-age=31536000, immutable. This lets browsers and others keep the same URL for a long time.

When you replace media, fetch the new URL from the delivery API. Don't assume the content at the same URL changes right away. Image URLs themselves can be fetched without an API key, so see Manage media for who can see them.

When it doesn't work as expected

For 400, check the values you set. For 415, check the format. If nothing is transformed, check the 25 MB limit and the animation rules. If the image stays small, check the original image's dimensions. Transformation times out after 20 seconds, including time in the queue, and returns 504 with the message Image transformation timed out.