tutorial6 分钟阅读

用 GPT Image 2 生成原生 4K 图像:宽高比与放大工作流

按当前 GPT Image 2 约定生成原生 4K:把 size 设为宽高比,把 resolution 设为 4k。文档中没有 upscale: true 开关,4K 的像素尺寸取决于你选择的比例。

ToAPIs Engineering & Evaluation Team
TL;DR - 核心要点
  • 精确型号 gpt-image-2 把 resolution 作为一等公民档位:1k、2k 和 4k。要原生 4K,在 POST /v1/images/generations 中发送 resolution: "4k",而不是服务端的 upscale: true 开关,也不是 1024x1024 这种 size 字符串。
  • size 是宽高比(1:1、16:9 以及其他已文档化的比例)。官方参考公布了像素对照表:16:9 在 4k 档是 3840x2160,1:1 在 4k 档是 2880x2880。
  • 当前 Playground 在 resolution 为 4K 时会去掉 5:4 和 4:5,尽管 API 尺寸表仍列出了这两个比例的 4k 像素值。若你需要它们,请以实时参考和实际请求为准。
  • 任务是异步的:请持久化任务 id,并轮询 GET /v1/images/generations/{id}。客户端超时并不等于任务失败,在 4k 档尤其如此。
  • 不要用旧的 1024px / 2048px 单价做预算。请在账户中确认该模型 ID 的实时分档费率。

用 GPT Image 2 生成原生 4K 图像:宽高比与放大工作流

目标型号:gpt-image-2
推理接口:https://api.toapis.com/v1/images/generations
相关阅读:GPT Image 2 API 指南 · 局部重绘与画布外扩 · 全球镜像与代理 · API 尺寸参考


1. 核心摘要与性能速览 (TL;DR)

  • 任务:用一次 gpt-image-2 请求,按你真正需要的宽高比,生成文档中的 4K 档图像,用于头图或印刷场景。
  • 约定:向 POST /v1/images/generations 发送型号 gpt-image-2。size 是宽高比(1:1、16:9 以及其他已文档化的比例)。resolution 是 1k、2k 或 4k。官方参考为每一对组合公布了对应的像素尺寸。
  • 不要发送:size: "2048x2048"、在精确型号 gpt-image-2 上使用 quality: "hd",或臆造一个 upscale: true 字段,声称能把 2048 px 渲染变成 3840x2160。4K 是一等公民的 resolution 值。
  • 异步协议:提交调用返回任务 id。轮询 GET /v1/images/generations/{id}(或 GET /v1/tasks/{id}),直到 completed 或 failed。4K 任务可能比 1K 打样更久;客户端超时并不等于任务失败。
  • FinOps:先用 1k 打样,把已接受的提示词提升到 4k,并确认实时分档费率。不要把旧的 1024 px / 2048 px 价格行复制进预测。

2. 宽高比、分辨率档位与原生 4K 输出

当前 gpt-image-2 约定把形状和档位分开:size 选择宽高比,resolution 选择质量档位,服务再由二者推导像素宽高。所以「一张 4K 图」并不总是 3840x2160——该尺寸是 size: "16:9" 加上 resolution: "4k" 的文档化结果。正方形 4K 输出的文档化尺寸是 2880x2880。

官方参考列出的预设比例为:

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

也可以传入 auto,由上游自行选择,但最终比例和像素尺寸将无法保证。精确型号 gpt-image-2 没有文档化的 custom 像素尺寸字段;自定义 width:height 比例(例如 7:4)写在 gpt-image-2-vip 和 gpt-image-2-official 上,并受其限制约束(边长须为 16 的倍数、长边最多 3,840 px、比例至多 3:1、总像素介于 655,360 与 8,294,400 之间)。

精确型号 gpt-image-2 的官方尺寸对照表如下:

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

这张表旁边需要同时记住两点:

  • 当前 ToAPIs Playground 在 4K 下仍保留 3:2 和 2:3,但会去掉 5:4 和 4:5。上表仍为这两个比例列出了 4k 像素值。若产品需要 4k 的 5:4 或 4:5,请用实时请求确认,不要把 Playground 的门禁直接当成 API 限制。
  • 不同界面会出现小写(4k)和大写(4K)。官方 gpt-image-2 示例使用小写;Playground 配置使用 1K / 2K / 4K。客户端请遵循 API 参考,不要把大小写当成第二个参数。

粗颗粒的 2×2 节点网格经六边形网关流入更细的高分辨率网格

图 1:分辨率是一等公民的请求字段。文档化的路径是直接请求 4k,而不是发明一个后处理放大开关。

ToAPIs 没有文档化的 upscale: true 开关,可以把原生 2048 px 渲染变成 3840x2160。如果你已有 1K 或 2K 图像并希望得到更大的结果,支持的做法是发起一次新的生成(可选地把草稿放入 reference_images),并将 resolution 设为 "4k"。除非你已在自己的素材上测过,否则不要承诺字体清晰度、「300 DPI 印刷母版」或无伪影放大。

精确型号 gpt-image-2 还接受可选的 background: "transparent",以及最多 14 个 reference_images URL。它在当前 Playground 约定中不暴露 quality;quality 是 gpt-image-2-vip 等型号上的字段。


3. 生产级实现:cURL 与 Python

本系列的国际示例使用 https://api.toapis.com。官方文档要求中国大陆用户使用 https://toapis.cn。每个环境只保留一个源站。

步骤 1:用 cURL 直接请求原生 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"
  }'

按文档,该请求对应 3840x2160。若需要正方形 4K 母版,将 size 改为 1:1(文档化为 2880x2880)。若需要 9:16 竖版,使用 size: "9:16"(文档化为 2160x3840)。

步骤 2:Python 先打样再提升

先在 1k 迭代,持久化已接受的提示词(以及可选的参考图 URL),再以 4k 重新提交。轮询辅助函数与镜像与代理指南使用同一套异步约定。

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))

给 4K 轮询的时限应长于 1K 打样。请立即持久化任务 id,这样即使客户端超时,仍可通过后续状态查询解决。若日后把客户端切到 gpt-image-2-vip(自定义比例、quality)或 gpt-image-2-official,请一次只改一个变量,并重读该型号的参考——计费单位不会自动相同。


4. 错误处理与状态码对照

下表只是排查起点,并不保证与 ToAPIs 的精确错误码一一对应。即便 HTTP 提交成功,仍须读取任务的 status。

HTTP 状态常见类别建议操作
400字段无效或不支持的组合确认 size 是已文档化的比例、resolution 是 1k / 2k / 4k,并且没有发送 2048x2048 这类像素字符串或未文档化的 upscale 开关
401API 密钥缺失或无效在 ToAPIs 控制台轮换密钥,并确认 Authorization 头
429速率或并发限制若响应含 Retry-After 请遵守;加入抖动后退避;仅在安全时重试
5xx 或网络超时网关或上游暂时异常重新提交前先查询任务状态;客户端超时后,4K 任务仍可能处于 in_progress

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


5. 定价与 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}

  • 不要沿用旧单价,例如 1024 px 的 $0.024 或 2048 px 的 $0.072。这些行属于已经过时的尺寸约定。
  • GPT Image 2 模型指南 当前展示的 ToAPIs 投放对照价,是标准 gpt-image-2 在 1K / 2K / 4K 下每张 $0.015 / $0.020 / $0.025。请只把它当作列表对照价,并确认适用于你的账户以及实际调用的型号 ID。
  • 节省成本的循环是:先在 1k 打样,再把已接受的提示词(和参考图)提升到 4k。两次成功提交就是两张计费图像,除非账户条款另有说明。文档中没有「同一提示词免费放大」的捷径。
  • 官方厂商的 token 价格与 ToAPIs 的按次价格不可混用。若改用 gpt-image-2-vip 或官方渠道型号,请重读该型号的价目。
  • 背景阅读见 GPT Image 2 定价文章,写入预测前请用实时目录核对每一个数字。

6. 常见问题

详见 frontmatter 中的 FAQ。摘要:4K 是一等公民的 resolution 值,不是 upscale 开关;像素尺寸同时取决于 size 和 resolution;不要把 1024x1024 当作 size;若需要 4k 的 5:4 / 4:5,请用实时 API 确认;1K / 2K / 4K 列表价须在账户中核对。


7. 行动清单

  • 在 ToAPIs 开发者门户 创建密钥。
  • 为每个环境设置一个基址(https://api.toapis.com,或在需要时使用 https://toapis.cn),并用 size: "16:9"、resolution: "1k" 对 cURL 片段做冒烟测试。
  • 把同一提示词提升到 resolution: "4k",并确认该比例的文档化像素尺寸(16:9 为 3840x2160)。
  • 持久化任务 id,给 4K 轮询更长的时限,并在 429 时遵守 Retry-After。
  • 接下来:若要编辑已有画面,阅读 局部重绘与画布外扩指南;更完整的参数表见 API 指南。

本文提到的模型与接口

OpenAIIMAGE

GPT-Image-2

当前费率:3 credits /request
OpenAIIMAGE

GPT-Image-2 VIP

当前费率:3.38 credits /request

相关技术文章

tutorial6 分钟阅读

掌握 GPT Image 2 图像编辑 API 的局部重绘与画布外扩

按当前 GPT Image 2 约定编辑已有图像:gpt-image-2 用参考图做提示词引导修改,gpt-image-2-official 用蒙版做精确局部重绘,两者都走异步的 generations 接口。

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2