Four concepts are routinely mixed together in image APIs: 1K, 2K and 4K tiers; aspect ratio; the request parameter; and the real width and height of the delivered file.
They all appear to describe image size, but they answer different questions. Separating them prevents a landscape asset from becoming portrait, avoids paying for resolution that does not help the current iteration, and makes pixel-level delivery requirements testable.
Separate the four layers first
Resolution tier
1K, 2K and 4K are generation tiers defined by a model or platform. They are not universal width-and-height constants shared by every image model.
A square, landscape and portrait image can all belong to the 1K tier while using different pixel dimensions. Providers can also use different pixel budgets and rounding rules for the same tier. A “4K” label alone is not enough to derive an exact size.
Aspect ratio
An aspect ratio describes canvas shape. 1:1 is square, 16:9 is widescreen landscape and 9:16 is vertical.
Ratio does not determine resolution. A 16:9 image can be a small preview or a high-resolution final.
API request value
An API normally accepts discrete values such as a size, image_size or aspect_ratio enum. It is not necessarily an unrestricted width and height input.
Valid values must come from the current model catalog. An upstream model may support a ratio that an aggregation route has not yet verified, priced or made routable.
Actual output pixels
Actual pixels are the decoded width × height of the delivered file. This is the value to record when accepting a production asset.
Some routes treat a tier as a target and return an approximate size. Others expose exact pixel presets. “Approximately 1K” and “exact pixels” are different delivery semantics.
Why K is not a fixed long edge
Google’s Gemini image generation guide provides a useful example. In the current Gemini 3.1 Flash Image table:
- 1K at
1:1is1024 × 1024; - 1K at
16:9is1376 × 768; - 2K at
16:9is2752 × 1536; - 4K at
16:9is5504 × 3072.
The tier and aspect ratio work together to select the output dimensions; the tier is not merely a name for one long-edge value. These numbers are examples from Google’s current official model table, not a universal size matrix for every OGA model or route.
Choose the ratio before the tier
The most reliable first question is where the image will be used, not whether 4K is available.
| Placement | Common ratios | Main concern |
|---|---|---|
| Product hero, avatar or icon | 1:1 |
Center the subject and leave crop-safe space |
| Article hero or desktop banner | 16:9, 3:2 |
Compose horizontally and keep important details away from edges |
| Mobile poster or short-video cover | 9:16, 4:5 |
Stack content vertically and reserve safe areas for copy and controls |
| Ultra-wide page background | 21:9 |
Limit subject count so the outer canvas remains useful |
After the shape is known, choose the resolution tier for the stage of work.
When to use 1K, 2K and 4K
1K: validate the idea and iterate
1K is a practical choice for composition tests, prompt iteration, thumbnails, inexpensive previews and large candidate sets. Most creative decisions are visible at this stage, so failed attempts do not need the highest tier.
2K: a balanced digital-delivery tier
2K often fits website heroes, campaign assets, product-detail graphics and digital work that needs some cropping room. It leaves space for post-processing without immediately taking on 4K latency and cost.
4K: a final after the composition is approved
4K is useful for large canvases, high-density displays, substantial cropping and final layout work. A higher tier does not repair incorrect text, anatomy or composition. Approving the content at a lower tier before producing a 4K final is usually more reliable than repeatedly rerunning 4K.
A reliable request sequence
- Use the models and pricing page to inspect current operations, ratios, tiers and request sizes.
- Pick the ratio from the final placement, not from which preview appears larger.
- Validate composition, subject, text and reference consistency at 1K or the lowest available tier.
- Move to 2K or 4K only after the content is approved.
- Decode the delivered file and store its real dimensions with the task and price snapshot.
- If a size is rejected, refresh the model catalog instead of guessing values in a retry loop.
Upstream capability is not current route capability
Google documents 0.5K, 1K, 2K and 4K for Gemini 3.1 Flash Image, while Gemini 3.1 Flash Lite Image currently supports 1K only. Models in the same family already require different resolution contracts.
OGA’s public pages expose only the current public contract. This article does not copy live price or route state. Before calling, use GET /api/v1/models/{model_id} as the source for sizes, tiers, ratios, size semantics and availability.
The practical rule is simple: ratio controls shape, tier controls generation scale, request values come from the current contract, and actual pixels are the acceptance evidence. Keeping those layers separate makes an image API predictable enough for production workflows.