Image requests now ask for an aspect and a resolution

This change replaces five fields on the shared image request in the AI package with two that travel between providers, an aspect ratio and a rough resolution tier. You ask for 16:9 at 2K, and each provider lowers it to its own parameters, approximates it with a notice, or fails with a typed error.

Slide text

packages/ai

feat(ai): portable image shape

Image.generate({ model, prompt,
  aspect: "16:9", resolution: "2K" })

Image.generate · Image.request · Video.generate

The old request carried size, aspect ratio, seed, mask and format, and most providers took one or two of them. Here's the support table the README carried for the main four. OpenAI took a size but no aspect ratio, and Google the reverse. So swapping the model usually meant a typed failure. An aspect ratio and a rough size tier are what travel between them.

Slide text

packages/ai

before

old field	size	aspectRatio	seed	mask	format
OpenAI	■	·	·	■	■
Google	·	■	■	·	·
xAI	·	■	·	·	·
Meta	hint	·	·	·	■

Fig. Support table, packages/ai/README.md, before this change. ■ lowers natively, · fails when set

The new request is small, modeled on OpenRouter's image API. Images and the image count are unchanged. Aspect ratio is now just aspect. Resolution is new, an open string with 1K, 2K and 4K as tiers. 1K means about as many pixels as 1024 by 1024, at your aspect. Leave both out, and the provider default applies.

Slide text

packages/ai

packages/ai/src/image.ts

The shared request is now small, modeled on OpenRouter's image API

Image.generate({
  model, prompt,
  images?,      // unchanged
  n?,           // unchanged
  aspect?,      // was aspectRatio
  resolution?,  // "1K" | "2K" | "4K"
  providerOptions?, http?,
})

1K ≈ the pixels of 1024×1024

at the requested aspect. Leave both out and the provider default applies.

Fig. The request shape, as written in the pull request

Here's how the main four lower it. Google passes both into its image config. xAI renders 1k or 2k, so a 4K request uses 2k, with a notice. OpenAI and the Vercel gateway compute a size within the model's limits, or take the nearest listed size on older models. Meta always renders about two and a half megapixels, so it ignores resolution and says so.

Slide text

packages/ai

src/protocols/*-images.ts

provider	aspect	resolution	when it can't match
Google	imageConfig.aspectRatio	imageConfig.imageSize	passed through as is
xAI	aspect_ratio	resolution 1k / 2k	4K uses 2k, with a notice
OpenAI + AI Gateway	gpt-image-2+: computed size within its limits; gpt-image-1, DALL·E: nearest listed size	same	a notice
Meta	size hint, W×H at that ratio	not sent	ignored, with a notice

Fig. How each of the main providers lowers the shared fields

The size math lives in one helper, used by 8 protocols. Fit turns an aspect and a tier into a width and height inside a provider's limits, rounding away from any limit it lands on. Nearest picks the closest listed size, aspect first, then pixel count. Notice flags a size more than 2 percent off the aspect, or more than root two off the tier per edge. Exact fits, or fails naming the closest size it would take.

Slide text

packages/ai

src/protocols/utils/image-sizing.ts · new, 124 lines

fit(shape, limits)

aspect + tier → width × height inside step, edge, pixel and ratio limits; rounds away from a limit it lands on

nearest(shape, sizes)

the closest listed size: aspect first, then pixel count

notice(name, shape, size)

a notice when the size misses the aspect by >2% or the tier by >√2 per edge

exact(route, shape, limits)

fit, or UnsupportedOperation naming the closest size it would take

Fig. 2K at 16:9 under a 2048² pixel cap is 2720x1536

When a size can't match, OpenAI, xAI and Meta still render. They put what they used in the response notices. BFL, fal, Z.ai, Alibaba, Cloudflare and Stability fail with UnsupportedOperation instead, naming the closest size they take. For the queued routes, Black Forest Labs and fal, that is the only option, because the result is decoded from the resume token alone, without the request.

Slide text

packages/ai

response.notices · AIError

renders, then says so

response.notices

OpenAI, Vercel AI Gateway, xAI, Meta

"OpenAI Images doesn't offer 16:9; used 1536x1024 (3:2)"

fails before the request is sent

UnsupportedOperation

BFL, fal, Z.ai, Alibaba, Cloudflare, Stability

"<route> can't render <aspect at resolution>; the closest size it takes is <W>x<H>"

Fig. Strings from image-sizing.test.ts and ImageSizing.exact

This breaks callers that pass size, seed, mask, format or aspect ratio. Here's the README's Google example before, and after. Aspect ratio becomes aspect, 2K moves up to the shared resolution field, and seed moves down into provider options. Video gets the same rename, and the ImageSize and ImageFormat exports give way to a new ImageResolution type.

Slide text

packages/ai

breaking

before

Image.generate({
  model: google.image(id),
  prompt,
  aspectRatio: "16:9",
  seed: 42,
  providerOptions: {
    imageSize: "2K",
  },
})

after

Image.generate({
  model: google.image(id),
  prompt,
  aspect: "16:9",
  resolution: "2K",
  providerOptions: {
    seed: 42,
  },
})

Video: aspectRatio → aspect · exports: ImageSize, ImageFormat removed · ImageResolution added

Everything else moved to typed provider options, on the routes that actually supported it. The whole map is on screen. On OpenAI and the gateway, a size option replaces aspect and resolution, so setting both fails. Meta's size works the same way against aspect. And xAI's own resolution option is gone, in favor of the shared field.

Slide text

packages/ai

breaking

route	new providerOptions
OpenAI / Vercel AI Gateway	size (replaces aspect and resolution), outputFormat, mask
Google	seed (imageSize removed, use resolution)
xAI	resolution option removed, use the shared field
Meta	size (with aspect fails), outputFormat
Black Forest Labs	width, height, seed, output_format, mask
fal	image_size (now also { width, height }), seed, output_format, mask
Stability (image, upscale)	seed, output_format
Z.ai	size
Alibaba	size (W*H), seed
Cloudflare Workers AI	width, height, seed

Fig. Where size, seed, mask and format went, per route

The recorded request bodies didn't change, so the test cassettes stayed as they were. Run live at 16:9, GPT Image 2 at 1K got 1360 by 768, the size fit computes. The older OpenAI model, Grok and Muse came back with notices, as designed. And Alibaba at 2K got 2720 by 1536, because 2736 wide is over its pixel cap.

Slide text

packages/ai

evidence

model	requested	got
gpt-image-1-mini	16:9, 1K	1536x1024 + notice
gpt-image-2	16:9, 1K	1360x768
gemini-3.1-flash-image	16:9, 1K	1376x768
grok-imagine-image	16:9, 4K	2816x1584 + notice (used 2k)
muse-image-1.0	16:9, 2K	2096x1184 + notice (resolution ignored)
AI Gateway bfl/flux-3-image-klein	16:9, 1K	1360x768
Alibaba qwen-image-2.0	16:9, 2K	2720x1536 (2736x1536 rejected, over 2048²)

Fig. Live runs from the pull request · recorded request bodies unchanged, cassettes not re-recorded

Two limits remain. Replicate still rejects aspect and resolution, because its inputs are defined per model, and the queued routes fail rather than approximate. If you call the AI package, rename aspect ratio to aspect, and move size, seed, mask and format into provider options. The size logic is in image-sizing.ts. Image requests now ask for an aspect and a resolution.

Slide text

packages/ai

limits · next

Replicate still rejects aspect and resolution. Queued routes (BFL, fal) fail rather than approximate.

Image requests now ask for an aspect and a resolution

aspectRatio → aspect; size, seed, mask, format → providerOptions

packages/ai/src/protocols/utils/image-sizing.ts github.com/anomalyco/opencode/pull/58528