掌握 GPT Image 2 图像编辑 API 的局部重绘与画布外扩
目标型号:
gpt-image-2、gpt-image-2-official
推理接口:https://api.toapis.com/v1/images/generations
相关阅读:GPT Image 2 API 指南 · 4K 宽高比工作流 · 全球镜像与代理 · 官方局部重绘参考
1. 核心摘要与性能速览 (TL;DR)
- 任务:替换已有图像的局部区域(局部重绘),或把画布扩展到新的宽高比(画布外扩),同时不要发明第二套未文档化的接口。
- 约定:只使用目录中真实存在的型号。精确型号
gpt-image-2接受prompt、作为比例的size、值为1k/2k/4k的resolution,以及可选的reference_images。带蒙版的局部重绘文档写在gpt-image-2-official上,字段是image_urls加上mask_url。 - 不属于当前约定:名为
gpt-image-2-edit的型号、同步的 multipartPOST /v1/images/edits,或size: "1024x1024"。这些形态出现在旧稿中,不应再复制到新客户端。 - 输入输出:先用
POST /v1/uploads/images上传原图和蒙版,再传入返回的公开 URL。reference_images、image_urls和mask_url都不接受 base64。 - 异步协议:提交调用返回任务
id。轮询GET /v1/images/generations/{id},直到completed或failed。客户端超时并不等于任务失败。
2. 可编程图像编辑的实际价值
用提示词从零生成只是第一步。生产环境中的商品图、广告和设计系统,更常见的需求是定向修改:更换单品、清理背景,或把方形包装图拉成宽屏头图,同时尽量保留光线和主体特征。
当前 ToAPIs 的 GPT Image 2 系列把这些工作放在同一条路径上:POST /v1/images/generations,区别只在型号:
| 任务 | 型号 ID | 如何指向原图 | 是否使用蒙版 |
|---|---|---|---|
| 提示词引导的编辑或风格迁移 | gpt-image-2 | reference_images(URL 列表,最多 14 张) | 该型号无文档化蒙版字段 |
| 像素级局部重绘 | gpt-image-2-official | image_urls(URL 列表,最多 16 张) | 须与首图一起提供 mask_url |
| 画布外扩 | 两个型号均可 | 把原图作为参考图,并把 size 改成目标比例 | 没有单独的 outpaint 开关 |
在精确型号 gpt-image-2 上,image_urls 是 reference_images 的向后兼容别名,网关会做归一化。官方渠道参考里的示例把 image_urls 与 mask_url 一起使用。请按你实际调用的型号,使用对应参考中的字段名。
可用的局部重绘蒙版是带 Alpha 通道的 PNG,像素尺寸必须与第一张参考图一致。透明像素(alpha = 0)是重绘区域,不透明像素应被保留。可在流水线中用 Pillow 等工具生成蒙版,先上传,再只发送 URL。
画布外扩是一种工作流,不是单独的接口。如果你有一张 1:1 包装图,需要 16:9 头图:把原图作为参考图,将 size 设为 16:9,显式指定 resolution 档位,并在提示词中要求保留主体、扩展场景。一种实用变体是把原图合成到更大的透明画布上,上传后再作为参考图——仍然走 /v1/images/generations,仍然没有 outpaint: true 这类开关。

图 1:原图画布与内部蒙版区域经过 ToAPIs 网关;文档化路径仍是 POST /v1/images/generations,mask_url 仅用于 gpt-image-2-official。
size 与 resolution 的约定与文生图相同:size 是 1:1 或 16:9 这样的比例,resolution 是 1k、2k 或 4k。精确型号 gpt-image-2 在当前 Playground 约定中不暴露 quality 字段;quality(low / medium / high)出现在 gpt-image-2-official 上。像素对照表见 4K 工作流指南。
3. 生产级实现:cURL 与 Python
本系列的国际示例使用 https://api.toapis.com。官方文档要求中国大陆用户使用 https://toapis.cn。每个环境只保留一个源站。路径、型号 ID 和 Bearer 头保持不变。
步骤 1:上传原图(如需蒙版,一并上传)
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@./product.png"
响应中包含 data.url。若调用的是 gpt-image-2-official,请对蒙版 PNG 再执行一次同样的上传。不要在生成请求里内联 base64。
步骤 2:在精确型号 gpt-image-2 上做提示词引导编辑
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": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": ["https://example.com/product.png"]
}'
步骤 3:在 gpt-image-2-official 上做蒙版局部重绘
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-official",
"prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"image_urls": ["https://example.com/photo.png"],
"mask_url": "https://example.com/mask.png"
}'
步骤 4:Python 提交与轮询
字段名请与你所调用型号的 API 参考保持一致。下面的片段使用文档中的图像状态路径,以及 completed / failed 状态。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def upload_image(path: str) -> str:
with open(path, "rb") as handle:
res = requests.post(
f"{BASE}/v1/uploads/images",
headers=HEADERS,
files={"file": handle},
timeout=60,
)
res.raise_for_status()
url = res.json().get("data", {}).get("url")
if not url:
raise RuntimeError(f"Unexpected upload envelope: {res.text}")
return url
def dispatch_edit(payload: dict) -> str:
res = requests.post(
f"{BASE}/v1/images/generations",
headers={**HEADERS, "Content-Type": "application/json"},
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 = 180) -> 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__":
source = upload_image("product.png")
# Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
task_id = dispatch_edit(
{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
"size": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": [source],
}
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
若要改为蒙版局部重绘,请先上传与首图尺寸一致的 RGBA 蒙版,将 model 改为 gpt-image-2-official,并发送 image_urls 与 mask_url。请把型号 ID、size 和 resolution 与任务记录一起保存,以便日后更换型号时是一次明确的决策。
4. 错误处理与状态码对照
下表只是排查起点,并不保证与 ToAPIs 的精确错误码一一对应。即便 HTTP 提交成功,仍须读取任务的 status。
| HTTP 状态 | 常见类别 | 建议操作 |
|---|---|---|
400 | 字段无效或不支持的组合 | 确认型号 ID、size 是已文档化的比例、resolution 是 1k / 2k / 4k、URL 可公开访问;若使用蒙版,须是与首图同尺寸、带 Alpha 通道的 PNG,且型号为 gpt-image-2-official |
401 | API 密钥缺失或无效 | 在 ToAPIs 控制台轮换密钥,并确认 Authorization 头 |
429 | 速率或并发限制 | 若响应含 Retry-After 请遵守;加入抖动后退避;仅在安全时重试 |
5xx 或网络超时 | 网关或上游暂时异常 | 重新提交前先查询任务状态;使用有上限的重试策略 |
5. 定价与 FinOps ROI
- 不要沿用规划旧稿中的单价,例如固定的
$0.024/$0.048「标准 vs HD」组合。这些数字已与当前目录脱节;当前目录按型号 ID 计价,标准 GPT Image 2 的投放页对照还按分辨率档位区分。 - GPT Image 2 模型指南 当前展示的 ToAPIs 投放对照价,是标准
gpt-image-2在1K/2K/4K下每张$0.015/$0.020/$0.025。请把它视为列表对照价,而不是合同账单。官方渠道型号和账户折扣可能不同;请确认你实际调用的型号费率。 - 选择
api.toapis.com还是toapis.cn只是源站选择,并不是文档中的折扣。FinOps 收益来自用1k打样、避免客户端超时后重复提交,以及选对型号(gpt-image-2与gpt-image-2-official),而不是臆造一个更便宜的「编辑」型号。 - 背景阅读见 GPT Image 2 定价文章,写入预测前请用实时目录核对每一个数字。
6. 常见问题
详见 frontmatter 中的 FAQ。摘要:精确型号 gpt-image-2 没有文档化的 mask_url 或 /v1/images/edits;蒙版局部重绘写在 gpt-image-2-official 上;蒙版必须是同尺寸的 RGBA PNG,并以 URL 传递;画布外扩是改 size 并传入参考图;计费须按准确的型号 ID 在账户中确认。
7. 行动清单
- 在 ToAPIs 开发者门户 创建密钥。
- 为每个环境设置一个基址(
https://api.toapis.com,或在需要时使用https://toapis.cn),并用POST /v1/uploads/images上传一张原图。 - 用
gpt-image-2做一次提示词引导编辑冒烟测试:传入reference_images,size: "1:1",resolution: "1k"。 - 若需要像素级蒙版,切换到
gpt-image-2-official,上传与首图尺寸一致的 RGBA 蒙版,并发送image_urls与mask_url。 - 持久化任务
id,在有限时限内轮询GET /v1/images/generations/{id},并在429时遵守Retry-After。 - 接下来:若要提高
resolution,阅读 4K 宽高比指南;更完整的参数表见 API 指南。







