tutorial6 分钟阅读

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

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

ToAPIs Engineering & Evaluation Team
TL;DR - 核心要点
  • 当前 ToAPIs 图像约定是异步的 POST /v1/images/generations,不是同步的 multipart /v1/images/edits,也不是名为 gpt-image-2-edit 的目录型号。
  • 精确型号 gpt-image-2 通过 reference_images(仅限公开 URL,最多 14 张)做提示词引导编辑。带 Alpha 蒙版的像素级局部重绘,文档写在 gpt-image-2-official 上,字段是 mask_url 加上 image_urls。
  • size 是宽高比(如 1:1 或 16:9),resolution 是 1k、2k 或 4k 档位。不要把 1024x1024 这种像素字符串当作 size。
  • 文档中没有单独的 outpaint 开关。要扩展画布,把 size 改成目标比例,把原图作为参考图传入,并在提示词里说明如何外扩。
  • 请持久化任务 id,并轮询 GET /v1/images/generations/{id}。客户端超时并不等于任务失败。

掌握 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 的型号、同步的 multipart POST /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-2reference_images(URL 列表,最多 14 张)该型号无文档化蒙版字段
像素级局部重绘gpt-image-2-officialimage_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:上传原图(如需蒙版,一并上传)

bash
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 上做提示词引导编辑

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": "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 上做蒙版局部重绘

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-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 状态。

python
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
401API 密钥缺失或无效在 ToAPIs 控制台轮换密钥,并确认 Authorization 头
429速率或并发限制若响应含 Retry-After 请遵守;加入抖动后退避;仅在安全时重试
5xx 或网络超时网关或上游暂时异常重新提交前先查询任务状态;使用有上限的重试策略

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}

  • 不要沿用规划旧稿中的单价,例如固定的 $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 指南。

本文提到的模型与接口

OpenAIIMAGE

GPT-Image-2

当前费率:3 credits /request
OpenAIIMAGE

gpt-image-2-official

当前费率:Input 800 credits/1M, Output 4,800 credits/1M

相关技术文章

tutorial6 分钟阅读

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

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

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2