tutorial6 min read

Generating Native 4K Images with GPT Image 2: Aspect Ratio and Upscaling Workflows

Generate native 4K output with the current GPT Image 2 contract: set size to an aspect ratio and resolution to 4k. There is no documented upscale: true flag, and 4K pixel size depends on the ratio you choose.

ToAPIs Engineering & Evaluation Team
TL;DR - Key Takeaways
  • Exact gpt-image-2 exposes resolution as a first-class tier: 1k, 2k, and 4k. Request native 4K by sending resolution: "4k" on POST /v1/images/generations — not a server-side upscale: true flag, and not a 1024x1024 size string.
  • size is an aspect ratio (1:1, 16:9, and the other documented ratios). The API reference publishes a pixel table; a 16:9 image at 4k is 3840x2160, while a 1:1 image at 4k is 2880x2880.
  • The current playground omits 5:4 and 4:5 when resolution is 4K, even though the API size table lists pixel values for those two ratios. Confirm against the live reference if you need them.
  • Jobs are asynchronous: persist the task id and poll GET /v1/images/generations/{id}. A client timeout is not proof the task failed, especially at 4k.
  • Do not budget from older 1024px / 2048px unit prices. Confirm the live per-tier rate for the exact model ID in your account.

Generating Native 4K Images with GPT Image 2: Aspect Ratio and Upscaling Workflows

Target Model: gpt-image-2
Inference Endpoint: https://api.toapis.com/v1/images/generations
Related: GPT Image 2 API guide · Inpainting and outpainting · Global mirror and proxy · API size reference


1. TL;DR & Performance Overview

  • Job: Produce a print- or hero-ready image at the documented 4K tier, with the aspect ratio you actually need, from a single gpt-image-2 request.
  • Contract: POST /v1/images/generations with model ID gpt-image-2. size is an aspect ratio (1:1, 16:9, and the other documented ratios). resolution is 1k, 2k, or 4k. The official reference publishes the resulting pixel dimensions for each pair.
  • What not to send: size: "2048x2048", a quality: "hd" flag on exact gpt-image-2, or an invented upscale: true field that claims to turn a 2048 px render into 3840x2160. 4K is a first-class resolution value.
  • Async protocol: The submit call returns a task id. Poll GET /v1/images/generations/{id} (or GET /v1/tasks/{id}) until completed or failed. 4K jobs can take longer than 1K drafts; a client timeout is not proof the task failed.
  • FinOps: Draft at 1k, promote accepted prompts to 4k, and confirm the live per-tier rate. Do not copy older 1024 px / 2048 px price rows into a forecast.

2. Aspect Ratios, Resolution Tiers, and Native 4K Output

The current gpt-image-2 contract splits shape from tier. size chooses the aspect ratio; resolution chooses the quality tier; the service derives the pixel width and height from both. That is why a "4K image" is not always 3840x2160 — that size is the documented result of size: "16:9" plus resolution: "4k". A square 4K output is documented as 2880x2880.

Preset ratios listed in the official reference are:

1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21

You can pass auto and let the upstream provider choose, but then the final ratio and pixel size are not guaranteed. Exact gpt-image-2 does not document a custom pixel-size field; custom width:height ratios (for example 7:4) are documented on gpt-image-2-vip and gpt-image-2-official, subject to their own limits (sides multiples of 16, long edge at most 3,840 px, ratio at most 3:1, total pixels between 655,360 and 8,294,400).

The API reference size table for exact gpt-image-2 is:

size1k2k4k
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

Two caveats belong next to that table:

  • The current ToAPIs playground keeps 3:2 and 2:3 at 4K, but it omits 5:4 and 4:5 when the resolution is 4K. The size table above still lists 4k pixels for those two ratios. If your product needs 5:4 or 4:5 at 4k, confirm with a live request rather than assuming the playground gate is the API limit.
  • Lowercase (4k) and uppercase (4K) appear in different surfaces. Official gpt-image-2 examples use lowercase; the playground config uses 1K / 2K / 4K. Follow the API reference in clients, and do not treat casing as a second parameter.

A coarse 2-by-2 node grid flowing through a hexagonal gateway into a finer high-resolution grid

Figure 1: Resolution is a first-class request field. The documented path is to ask for 4k directly, not to invent a post-processing upscaler flag.

There is no documented ToAPIs upscale: true switch that takes a native 2048 px render and returns 3840x2160. If you already have a 1K or 2K image and want a larger one, the supported move is a new generation (optionally with the draft in reference_images) at resolution: "4k". Do not promise typography fidelity, "300 DPI print masters," or artifact-free upscaling unless you have measured those properties on your own assets.

Exact gpt-image-2 also accepts optional background: "transparent" and up to 14 reference_images URLs. It does not expose quality in the current playground contract; quality is a field on IDs such as gpt-image-2-vip.


3. Production Implementation: cURL & Python

International examples in this series use https://api.toapis.com. Official docs tell mainland China users to use https://toapis.cn. Keep one origin per environment.

Step 1: cURL dispatch at native 4K

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
    "size": "16:9",
    "resolution": "4k",
    "n": 1,
    "response_format": "url"
  }'

This request is documented to target 3840x2160. For a square 4K master, change size to 1:1 (documented as 2880x2880). For a 9:16 story frame, use size: "9:16" (documented as 2160x3840).

Step 2: Python draft-then-promote helper

Iterate at 1k, persist the accepted prompt (and optional reference URLs), then resubmit at 4k. The poll helper is the same async contract used in the mirror and proxy guide.

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_image(
    prompt: str,
    size: str = "16:9",
    resolution: str = "1k",
    model: str = "gpt-image-2",
    reference_images: list[str] | None = None,
) -> str:
    payload = {
        "model": model,
        "prompt": prompt,
        "size": size,
        "resolution": resolution,
        "n": 1,
        "response_format": "url",
    }
    if reference_images:
        payload["reference_images"] = reference_images
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(
        f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
    )


if __name__ == "__main__":
    prompt = (
        "Wide architectural photograph of a concrete pavilion at dusk, "
        "still water in the foreground, no typography, no logos"
    )
    draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
    print("Draft:", draft_id, poll_image_task(draft_id))
    final_id = dispatch_image(prompt, size="16:9", resolution="4k")
    print("4K:", final_id, poll_image_task(final_id, deadline_s=300))

Give 4K polls a longer deadline than 1K drafts. Persist the task id immediately so a client timeout can still be resolved by a later status check. If you later switch the client to gpt-image-2-vip (custom ratios, quality) or gpt-image-2-official, change one variable at a time and reread that ID's reference — billing units are not automatically the same.


4. Error Handling & Status Matrix

The categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes. A successful HTTP submit still requires you to read task status.

HTTP statusCommon categoryRecommended action
400Invalid field or unsupported combinationCheck that size is a documented ratio, that resolution is 1k / 2k / 4k, and that you did not send a pixel string such as 2048x2048 or an undocumented upscale flag
401Missing or invalid API keyRotate the key in the ToAPIs dashboard and confirm the Authorization header
429Rate or concurrency limitHonor Retry-After when present; back off with jitter; retry only when safe
5xx or network timeoutTemporary gateway or upstream issueCheck task status before resubmitting; 4K jobs may still be in_progress after a client timeout

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. Pricing & FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • Do not reuse older unit prices such as $0.024 for 1024 px or $0.072 for 2048 px. Those rows belong to a stale size contract.
  • The GPT Image 2 model guide currently shows a ToAPIs landing comparison of $0.015 / $0.020 / $0.025 per image at 1K / 2K / 4K for standard gpt-image-2. Use that only as a listed comparison. Confirm the rate that applies to your account and to the exact model ID you call.
  • A cheap loop is draft at 1k, then promote the accepted prompt (and references) to 4k. Two successful jobs are two billable images unless your account terms say otherwise. There is no documented free "upscale the same prompt" shortcut.
  • Official-vendor token prices and ToAPIs per-request prices are not interchangeable. If you move to gpt-image-2-vip or an official-channel SKU, reread that ID's price sheet.
  • For background, see the GPT Image 2 pricing article, then verify every number against the live catalog before you put it in a forecast.

6. Frequently Asked Questions

See the FAQ block in frontmatter. Summary: 4K is a first-class resolution value, not an upscale flag; pixel dimensions depend on both size and resolution; do not send 1024x1024 as size; confirm 5:4 / 4:5 at 4k against the live API if you need those ratios; confirm the listed 1K / 2K / 4K rates in your account.


7. Action Checklist

  • Create a key on the ToAPIs Developer Portal.
  • Set one base URL per environment (https://api.toapis.com or, where required, https://toapis.cn) and smoke-test the cURL snippet at size: "16:9" and resolution: "1k".
  • Promote the same prompt to resolution: "4k" and confirm the documented pixel size for that ratio (for 16:9, 3840x2160).
  • Persist the task id, give 4K polls a longer deadline, and honor Retry-After on 429.
  • Next: the inpainting and outpainting guide if you are editing an existing frame, and the API guide for the broader parameter map.

Explore Models Mentioned in This Post

OpenAIIMAGE

GPT-Image-2

Current Rate: 3 credits /request
OpenAIIMAGE

GPT-Image-2 VIP

Current Rate: 3.38 credits /request

Related Articles

tutorial6 min read

Mastering Inpainting and Outpainting with GPT Image 2 Image Edits API

Edit existing images with the current GPT Image 2 contract: reference-guided changes on gpt-image-2, and mask-based inpainting on gpt-image-2-official — all on the async generations endpoint.

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2