亿速API文档中心

图片 API

GPT-Image-2 概览

GPT-Image-2 生图/编辑

功能概览

本页用于说明 GPT-Image-2 概览 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

  • 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
  • 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
  • 能力迁移适配：适合从原有模型或 SDK 平滑切换到亿速API统一接口。

接入建议

  • 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
  • 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
  • 上线前建议准备日志追踪、错误兜底和内容安全校验，便于稳定运行。

概述

gpt-image-2 是 OpenAI 最新旗舰图像生成模型，是 gpt-image-1.5 的升级版。核心升级：任意合法分辨率、参考图自动高保真。亿速API 网关完整兼容 OpenAI Images API，OpenAI 官方 SDK 把 base_url 指过来即可零代码改动直连。

文生图 API

/v1/images/generations，输入文本提示词生成图片，支持 size / quality / output\_format。

图片编辑 API

/v1/images/edits，multipart 上传参考图+ 编辑/融合指令，支持 mask 局部重绘。

为什么选 亿速API 的 GPT-image-2 官转？

官方通道 · 与官方一致

严格走 OpenAI 官方转发链路，请求和响应 100% 与 OpenAI 官方一致——字段、错误码、模型行为完全相同，质量无损、无偷跑风险。

不限并发 · 企业可放量

不受 OpenAI 官方 Tier 等级 对 RPM / TPM 的硬限，企业量级请求可线性放大，批量生图与高峰场景更从容。

全球零门槛接入

无需海外服务器或代理，国内机房、家宽网络、海外节点均可直连 api.yisu.com，延迟稳定、免去出海改造。

专业服务 · 企业陪跑

团队深耕图像生成场景，具备丰富的选型、调优与集成经验，可为企业客户提供从 PoC 到生产上线的完整技术支持。

核心特性

任意分辨率

支持合法尺寸输出，自定义尺寸只需满足边长 16 倍数、比例 ≤ 3:1 等基本约束。

参考图自动高保真

编辑场景下自动启用 high-fidelity，参考图细节、人物身份、文字内容保留度大幅提升。无需也不能再传 input_fidelity。

中文 + 文字渲染

中文提示词原生支持，招牌、海报、UI 截图等场景的中英文文字渲染稳定，high 档位下精细文字几乎不糊。

多图融合

image[] 数组参考图，prompt 中可用「图1/图2/图3」明确指代。

mask 局部重绘

支持上传带 alpha 通道的 mask 图，透明区域为重绘区，不透明区域保留原图。

多种输出格式

支持 png（默认）。

OpenAI SDK 直连

把 base_url 指向 https://api.yisu.com/v1 即可用 OpenAI 官方 SDK 直接调用，零代码改动迁移。

技术规格

维度参数
模型名gpt-image-2
速度约 120 秒
输出分辨率合法尺寸（1K/2K/4K）
画质档位auto / low / medium / high
输出格式png（默认）/ jpeg / webp
中文提示词✅ 原生支持
单次出图数量1 张（n=1）
mask 局部重绘✅ 支持（要求带 alpha 通道）
透明背景❌ 不支持（background: transparent 会报错）
响应字段b64_json（纯 base64，无前缀）

端点一览

端点用途Content-Type
POST /v1/images/generations文生图application/json

域名选择：api.yisu.com 为主域名，也可使用 ` / ` 等平台提供的其他网关域名，响应行为一致。

尺寸（size）详解

预设尺寸

size含义
auto自适应（默认）
256x256方形 1:1
512x512方形 1:1
1024x1024方形 1:1
1536x1024横版 3:2
1024x1536竖版 2:3
2048x2048方形 1:1
1792x1024横版 16:9
1024x1792横版 16:9

最佳实践

对接经验：先用 low 跑通，再按需升档

实测有客户首次接入就直接拉满 quality=high + 高分辨率，单张耗时 ≈ 235 秒（约 4 分钟），一度误以为是接口卡住。high 模式推理复杂度最高，4K 场景甚至接近 5 分钟。正式上线前请先用 quality=low 跑通整条链路（鉴权、SDK、参数、超时、错误处理），确认功能 OK 后再按业务对画质的实际需求逐档升到 medium / high。

对接先跑 low 验证链路

新接入时优先用 quality=low + 预设尺寸跑通整条链路（鉴权、参数、超时、错误处理）。low 速度比 high 快数倍，能快速暴露所有非画质相关的问题，避免被长耗时干扰排查。

尺寸优先选预设

8 个预设尺寸经过官方优化，速度和质量更稳定；自定义尺寸留给真有比例需求的场景。

画质按场景分档

草稿 / 批量 → low；默认 / 终稿 → medium；文字、精细纹理、印刷 → high。注意 low ↔ high 不仅是画面精美度差异，还包含推理复杂度差异——耗时差距可达数倍。

输出格式选 JPEG

对最终展示无特别要求时，output_format=jpeg + output_compression=85 比 PNG 快且体积小一半以上。

文字场景锁 high

文字渲染是主要卖点，但 low/medium 仍可能糊；招牌、海报类场景锁 quality=high。

超时分档配置（high 兜底 600 秒）

影响出图耗时最大的是 quality 与 size，尤其是 quality。建议按档位配置客户端超时：

quality推荐客户端超时实测耗时区间
low≥ 120 秒通常 10–40 秒
medium≥ 240 秒通常 30–90 秒
high≥ 600 秒（兜底）2K/4K 实测 3–5 分钟，长尾可达 235 秒以上

high 模式务必配 600 秒兜底，覆盖排队 / 长尾 / 服务抖动等各种异常情况；前端务必给进度反馈；服务端建议用任务队列解耦。

迁移注意

从 gpt-image-1.5 迁移：删掉 input_fidelity（强制高保真，传了会报错）；避开 background: transparent（暂不支持）。

错误码与重试

状态码含义处理建议
400参数非法（size 不合约束、传了不支持的字段等）按尺寸约束章节校验；注意不要传 input_fidelity / background: transparent
401令牌无效检查 Bearer Token
403内容审核拦截调整 prompt 或传 moderation: low
5xx网关 / 后端错误重试 1–2 次
超时长尾客户端超时按 quality 分档：low ≥ 120 秒 / medium ≥ 240 秒 / high ≥ 600 秒（high + 2K/4K 实测 3–5 分钟，长尾可达 235 秒以上）

建议客户端：

  • 请求超时按 quality 分档配置：low ≥ 120 秒 / medium ≥ 240 秒 / high ≥ 600 秒（兜底；实测 3–5 分钟，按 120/360 秒配会大量误超时）
  • 新接入先用 quality=low 跑通链路，再按需升到 medium / high
  • 对 5xx 与超时做 指数退避重试（建议 2 次）
  • 记录响应头 x-request-id 方便排查

常见问题

返回的 b64_json 要不要自己加 data:image/png;base64, 前缀？

要。gpt-image-2 返回的是纯 base64 字符串（无前缀），与 gpt-image-2-all 不同。客户端有两种用法：

  • 写文件：base64.b64decode(b64_str) 后写入磁盘
  • 浏览器渲染：img.src = 'data:image/png;base64,' + b64_str 自行拼前缀

若你的代码沿用了 1.5 时代的"已含前缀"假设，会拿到损坏的 data URL，请显式判断。

为什么传 input_fidelity 会报 400？

gpt-image-2 强制启用 high-fidelity 处理参考图，不再接受 input_fidelity 参数。从 1.5 迁移时把这个字段移除即可，无需替换。

想要透明背景怎么办？

gpt-image-2 暂不支持 background: transparent（会报错）。两个变通方案：

  • 把 background 改为 opaque / 或不传，自行用 PIL / sharp / 在线工具抠透明
  • 仍需透明背景的场景临时回退到 gpt-image-1.5
mask 文件怎么准备？
  • 与原图相同尺寸、相同格式，单张 ≤ 50MB
  • 必须带 alpha 通道：透明区域（alpha=0）= 要重绘的部分，不透明区域 = 保留
  • 仅对第一张 image 生效
  • mask 是"软引导"非精确边界，模型可能在蒙版周围扩展 / 收敛
和 gpt-image-2-all 怎么选？
选场景
gpt-image-2（官方）需要精确控制 size / quality、要求与 OpenAI 官方完全一致、要 4K 出图、要 mask 局部重绘
能用 OpenAI 的官方 SDK 直连吗？

可以，零代码改动。把 base_url 指向 https://api.yisu.com/v1，api_key 设为 亿速API 令牌即可：

    from openai import OpenAI
    client = OpenAI(api_key="sk-your-key", base_url="https://api.yisu.com/v1")
    resp = client.images.generate(model="gpt-image-2", prompt="...", size="2048x1152", quality="high")
生成失败会扣费吗？ 
    {
      "status_code": 400,
      "error": {
        "message": "Your request was rejected by the safety system. ...",
        "type": "shell_api_error",
        "code": "moderation_blocked"
      }
    }

<Info>以上文档供参考，按实际为准。