用 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 的官方尺寸对照表如下:
| size | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
3:2 | 1536x1024 | 2048x1360 | 3520x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3520 |
4:3 | 1024x768 | 2048x1536 | 3312x2480 |
3:4 | 768x1024 | 1536x2048 | 2480x3312 |
5:4 | 1280x1024 | 2560x2048 | 3216x2576 |
4:5 | 1024x1280 | 2048x2560 | 2576x3216 |
16:9 | 1536x864 | 2048x1152 | 3840x2160 |
9:16 | 864x1536 | 1152x2048 | 2160x3840 |
2:1 | 2048x1024 | 2688x1344 | 3840x1920 |
1:2 | 1024x2048 | 1344x2688 | 1920x3840 |
21:9 | 2016x864 | 2688x1152 | 3840x1648 |
9:21 | 864x2016 | 1152x2688 | 1648x3840 |
这张表旁边需要同时记住两点:
- 当前 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 参考,不要把大小写当成第二个参数。

图 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
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 重新提交。轮询辅助函数与镜像与代理指南使用同一套异步约定。
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 开关 |
401 | API 密钥缺失或无效 | 在 ToAPIs 控制台轮换密钥,并确认 Authorization 头 |
429 | 速率或并发限制 | 若响应含 Retry-After 请遵守;加入抖动后退避;仅在安全时重试 |
5xx 或网络超时 | 网关或上游暂时异常 | 重新提交前先查询任务状态;客户端超时后,4K 任务仍可能处于 in_progress |
5. 定价与 FinOps ROI
- 不要沿用旧单价,例如 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 指南。







