gpt image 2 official api integration guide image 0 图示

gpt-image-2 接入官方 API 的 9 步实战指南：从零到生产

作者

OpenAI 在 2026 年 4 月发布的 gpt-image-2 已成为图像生成赛道最受关注的模型——99% 字符级文字渲染准确率、4K 高清输出、原生中文/CJK 支持、O 系列推理能力整合。但很多开发者拿到模型后第一个问题就是：gpt-image-2 接入官方 API 究竟应该怎么做？哪些参数是必需的？base_url 怎么配？响应里的 b64_json 拿到后该怎么用？

本文是一份端到端的 gpt-image-2 接入官方 API 实战指南，覆盖从 SDK 安装、base_url 配置到文生图、图片编辑、inpainting、错误处理的全部技术细节。所有代码都基于 OpenAI 官方 SDK 和 APIYI 官转通道（与官方字段 100% 一致），跑完本文你的项目就能立即在生产环境使用 gpt-image-2。

gpt-image-2-official-api-integration-guide 图示

gpt-image-2 接入官方 API 的准备工作清单

在写第一行代码之前，需要先把环境准备好。下面这份清单覆盖了 gpt-image-2 接入官方 API 必须的 4 个先决条件。

gpt-image-2 接入官方 API 的环境清单

准备项 要求 说明
API Key 有效 Bearer Token 通过 APIYI 控制台申请，注册即可获取测试额度
Python SDK openai >= 1.50.0 旧版本不支持 images.generate() 的新参数
Node.js SDK openai >= 4.50.0 TypeScript 类型已同步官方
HTTP 超时 ≥ 360 秒 high 画质 + 2K/4K 实测耗时 3-5 分钟
网络要求 国内可直连 api.apiyi.com 国内/家宽/海外节点均可访问

gpt-image-2 接入官方 API 的 SDK 安装

无论选择哪种语言，安装 OpenAI 官方 SDK 即可——APIYI 官转通道与官方字段完全一致，不需要额外的客户端库。

# Python
pip install --upgrade openai

# Node.js
npm install openai@latest

# 如果使用 yarn / pnpm
yarn add openai
pnpm add openai

gpt-image-2 接入官方 API 的 API Key 获取流程

获取 API Key 的步骤极简：

  1. 访问 APIYI 控制台 api.apiyi.com
  2. 注册账户后进入「API 令牌」页面
  3. 创建新 Token（建议为不同项目使用独立 Token 便于审计）
  4. 将 Token 保存到环境变量（强烈不建议硬编码到代码）

🚀 快速上手建议：首次接入 gpt-image-2 官方 API 时，推荐先用低画质 + 1024×1024 跑通链路，再切换到 high 画质和大尺寸。我们建议通过 API易 apiyi.com 平台领取测试额度，免费额度足够完成 PoC 全流程验证。

# 在 ~/.zshrc 或 ~/.bashrc 中加入
export APIYI_KEY="sk-your-token-here"

gpt-image-2 接入官方 API 的 base_url 配置

整个 gpt-image-2 接入官方 API 流程中，唯一与原生 OpenAI SDK 不同的就是 base_url。把它从 api.openai.com 替换为 api.apiyi.com，其他代码全部保持一致。

gpt-image-2-official-api-integration-guide 图示

gpt-image-2 接入官方 API 的两个端点

APIYI 提供与 OpenAI 完全一致的两个图像端点：

端点 用途 必需参数
POST /v1/images/generations 文生图（纯 prompt 生成） model、prompt
POST /v1/images/edits 图片编辑、多图融合、mask 重绘 model、prompt、image

gpt-image-2 接入官方 API 的客户端初始化

下面给出 Python 和 Node.js 的客户端初始化代码，记住一定要把超时设置到 360 秒以上。

# Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",  # 切到 APIYI 官转通道
    timeout=600.0,                         # 高画质场景必须延长
    max_retries=2
)

// Node.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_KEY,
  baseURL: "https://api.apiyi.com/v1",  // 注意是 baseURL（驼峰）
  timeout: 600 * 1000,                  // 毫秒
  maxRetries: 2
});

💡 超时设置提醒：默认的 60 秒超时在 high 画质 + 2K/4K 场景下必然失败。我们建议通过 API易 apiyi.com 接入时，所有生产环境客户端的请求超时都设置在 360-600 秒区间，避免长尾请求被错误中断。

gpt-image-2 接入官方 API 的文生图调用

进入实战环节。下面用三种语言展示如何完成第一次 gpt-image-2 接入官方 API 的文生图调用。

gpt-image-2 接入官方 API 的 Python 文生图

import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="A modern minimalist office desk with a vintage typewriter, soft morning light from the window, photorealistic, 8K",
    size="1536x1024",
    quality="high",
    output_format="jpeg",
    output_compression=92,
    n=1
)

# 关键: APIYI 返回的是纯 base64 字符串，无 data:image/... 前缀
b64 = response.data[0].b64_json
with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(b64))

print("✓ 图像已保存到 output.jpg")

gpt-image-2 接入官方 API 的 Node.js 文生图

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_KEY,
  baseURL: "https://api.apiyi.com/v1",
  timeout: 600_000
});

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt: "An e-commerce product photo of a leather backpack on a marble desk, studio lighting",
  size: "1024x1024",
  quality: "high",
  output_format: "png",
  n: 1
});

const b64 = response.data[0].b64_json;
await fs.writeFile("output.png", Buffer.from(b64, "base64"));
console.log("✓ 图像已保存");

gpt-image-2 接入官方 API 的 cURL 文生图

cURL 适合快速验证 API Key 可用性、测试新参数组合。

curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer $APIYI_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic cyberpunk city at night, neon signs in mixed Chinese and English",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 90,
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 -d > output.jpg

注意 --max-time 600 必加——cURL 默认无超时，但很多 shell 包装会加上 60 秒强制中断。

gpt-image-2 接入官方 API 的响应处理要点

很多开发者第一次接入时会卡在 base64 解析。下面是几个容易踩坑的点：

# ✗ 错误：APIYI 不返回 url 字段
url = response.data[0].url  # AttributeError

# ✓ 正确：使用 b64_json
b64 = response.data[0].b64_json

# ✗ 错误：浏览器直接渲染纯 b64 字符串
<img src="{b64}">  # 不会显示

# ✓ 正确：浏览器渲染需手动拼接前缀
data_uri = f"data:image/jpeg;base64,{b64}"
# <img src="{{ data_uri }}">

# ✓ 正确：服务端保存到磁盘
with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(b64))

gpt-image-2 接入官方 API 的完整参数详解

掌握每个参数的取值范围和适用场景，是 gpt-image-2 接入官方 API 进入生产环境的关键。

gpt-image-2-official-api-integration-guide 图示

gpt-image-2 接入官方 API 的核心参数表

参数 取值 默认值 说明
model "gpt-image-2" 必填 模型 ID
prompt 字符串 必填 提示词，支持中英文混合
size 8 种预设 + 自定义 auto 详见下表
quality auto / low / medium / high auto 影响成本和耗时
output_format png / jpeg / webp png 推荐 jpeg + 90 压缩
output_compression 1-100 100 仅对 jpeg/webp 生效
moderation auto / low auto low 降低审核敏感度
n 1-10 1 单次生成数量

gpt-image-2 接入官方 API 的 size 参数完整选项

# 8 种官方预设
size = "1024x1024"   # 1:1 标准方图
size = "1536x1024"   # 3:2 横版
size = "1024x1536"   # 2:3 竖版
size = "2048x2048"   # 2K 方图
size = "2048x1152"   # 16:9 横版（适合电脑壁纸/海报）
size = "3840x2160"   # 4K 横版
size = "2160x3840"   # 4K 竖版（适合手机壁纸）
size = "auto"        # 由模型自动选择

如果需要自定义尺寸，必须满足以下约束：

✓ 边长是 16 的整数倍
✓ 最大边长 ≤ 3840px
✓ 长短边比例 ≤ 3:1
✓ 总像素在 655,360 ~ 8,294,400 之间

例如 1280x720（720P）合法，3840x1080（超宽屏）会因为比例 > 3:1 被拒绝。

gpt-image-2 接入官方 API 的 quality 与成本对照

quality 是影响成本最大的参数。下面是完整定价对照表（每张图）。

画质 1024×1024 1024×1536 1536×1024 适用场景
low $0.006 $0.005 $0.005 草图、缩略图、快速迭代
medium $0.053 $0.041 $0.041 内容站、自媒体配图
high $0.211 $0.165 $0.165 商品图、海报、广告物料

💰 成本优化：日均生图 100 张的内容团队，使用 medium 画质比 high 节省 75% 成本。我们建议通过 API易 apiyi.com 平台先用 low 画质快速跑 prompt 调优，定稿后再升级到 medium/high 出最终图，能把月度图像生成预算降低 30-50%。

gpt-image-2 接入官方 API 的 output_format 选择

输出格式直接影响存储成本和加载速度：

# 透明背景需求？gpt-image-2 不支持，会报 400
# ✗ output_format="png", background="transparent" → 400 Bad Request

# 网页/小程序展示：jpeg + 压缩 90
output_format="jpeg", output_compression=90

# 高保真存档：png（无损）
output_format="png"

# 现代 Web 应用：webp 体积最小
output_format="webp", output_compression=85

gpt-image-2 接入官方 API 的图片编辑与 inpainting

除了文生图，gpt-image-2 还支持图片编辑、多图融合、局部重绘（inpainting/outpainting）三大编辑场景。

gpt-image-2-official-api-integration-guide 图示

gpt-image-2 接入官方 API 的图片编辑（参考图模式）

参考图编辑会自动启用 high-fidelity 模式——所以不要传 input_fidelity 参数（会被拒绝）。

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1"
)

# 单张参考图编辑
with open("source.jpg", "rb") as img:
    response = client.images.edit(
        model="gpt-image-2",
        image=img,
        prompt="把背景换成日落海滩，保留前景人物姿势和服装",
        size="1024x1024",
        quality="high"
    )

gpt-image-2 接入官方 API 的多图融合（最多 16 张）

/images/edits 端点支持最多 16 张参考图同时输入，prompt 中用「图1/图2/图3」指代。

images = [
    open("character.jpg", "rb"),     # 图1：角色
    open("background.jpg", "rb"),    # 图2：背景
    open("outfit.jpg", "rb"),        # 图3：服装参考
]

response = client.images.edit(
    model="gpt-image-2",
    image=images,
    prompt="将图1的角色放置在图2的背景中，让角色穿上图3的服装风格，保持电影质感",
    size="2048x1152",
    quality="high"
)

这个能力在电商商品换背景、虚拟试穿、漫画分镜生成等场景极为强大。

gpt-image-2 接入官方 API 的 Inpainting 局部重绘

Inpainting 通过 mask 参数指定要重绘的区域。关键规则：

  • mask 必须与第一张参考图尺寸一致
  • mask 是带 alpha 通道 的 PNG
  • 透明区域 = 要重绘的区域
  • 不透明区域 = 保持原图
with open("photo.png", "rb") as img, open("mask.png", "rb") as msk:
    response = client.images.edit(
        model="gpt-image-2",
        image=img,
        mask=msk,
        prompt="把红框区域换成一只橙色的猫",
        size="1024x1024",
        quality="high"
    )

如果你需要在 Python 中程序化生成 mask，可以用 PIL：

from PIL import Image

# 创建一个与原图同尺寸的 mask，默认全黑（不透明 = 保留）
mask = Image.new("RGBA", (1024, 1024), (0, 0, 0, 255))

# 把要重绘的区域改为透明（alpha=0）
for x in range(400, 700):
    for y in range(300, 600):
        mask.putpixel((x, y), (0, 0, 0, 0))

mask.save("mask.png")

gpt-image-2 接入官方 API 的错误处理与生产实践

把 gpt-image-2 接入官方 API 推到生产，必须处理好错误码、并发、超时三大问题。

gpt-image-2 接入官方 API 的完整错误码表

HTTP 状态码 含义 推荐处理
400 参数非法（size 越界、传了不支持字段） 校验输入；不要传 input_fidelity 或 background:transparent
401 令牌无效 检查 Bearer Token、确认未过期
403 内容审核拦截 调整 prompt，或加 moderation: "low"
429 限流 / 余额不足 指数退避重试 + 余额检查
5xx 网关或后端错误 重试 1-2 次，仍失败上报告警
超时 长尾请求未及时响应 客户端超时设到 ≥ 360 秒

gpt-image-2 接入官方 API 的指数退避重试

下面是一个生产级的重试封装，处理 429 和 5xx：

import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

def generate_with_retry(prompt: str, max_retries: int = 5):
    delay = 1.0
    for attempt in range(max_retries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high"
            )
        except RateLimitError:
            sleep = delay + random.uniform(0, 0.5)
            print(f"429 限流，{sleep:.1f}s 后重试 ({attempt+1}/{max_retries})")
            time.sleep(sleep)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < max_retries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("超过最大重试次数")

gpt-image-2 接入官方 API 的并发控制

批量任务用 asyncio.Semaphore 限制并发数，避免短时打爆下游：

import asyncio
from openai import AsyncOpenAI

aclient = AsyncOpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

async def gen_one(prompt: str, sem: asyncio.Semaphore):
    async with sem:
        return await aclient.images.generate(
            model="gpt-image-2",
            prompt=prompt,
            size="1024x1024",
            quality="medium"
        )

async def batch(prompts: list[str], concurrency: int = 30):
    sem = asyncio.Semaphore(concurrency)
    return await asyncio.gather(*[gen_one(p, sem) for p in prompts])

# 跑 200 张图，30 路并发
prompts = [f"商品场景图变体 #{i}" for i in range(200)]
results = asyncio.run(batch(prompts))

gpt-image-2 接入官方 API 的成本预估

生产前先做成本预估。下面是几个典型场景的月度费用估算：

业务场景 日均量 画质 月成本估算
自媒体配图 30 张 medium ~$48
电商商品图 200 张 high ~$1266
SaaS 用户生图 1000 次 medium ~$1590
游戏关键帧 500 张 high ~$3165

🎯 生产部署建议：建议为不同业务线申请独立 API Token 便于成本归因和限流隔离。我们建议通过 API易 apiyi.com 控制台开启账单告警，当月度消耗达到预设阈值时自动通知，避免预算超支。

gpt-image-2 接入官方 API 的可观测性

生产环境务必记录每次请求的关键指标：

import time
import logging

logger = logging.getLogger("gpt-image-2")

def call_with_metrics(prompt: str, **params):
    start = time.perf_counter()
    try:
        resp = client.images.generate(model="gpt-image-2", prompt=prompt, **params)
        latency = time.perf_counter() - start
        logger.info(
            "gpt-image-2 ok",
            extra={
                "latency_ms": int(latency * 1000),
                "size": params.get("size"),
                "quality": params.get("quality"),
                "n": params.get("n", 1)
            }
        )
        return resp
    except Exception as e:
        logger.error(f"gpt-image-2 failed: {type(e).__name__}: {e}")
        raise

关于 gpt-image-2 接入官方 API 的常见问题 FAQ

Q1：gpt-image-2 接入官方 API 时为什么会出现 input_fidelity 报 400？

gpt-image-2 在所有编辑场景自动启用 high-fidelity，因此 input_fidelity 参数被拒绝。直接删掉这个参数即可。如果你的代码是从 gpt-image-1 迁移过来，需要全局搜索移除。我们建议通过 API易 apiyi.com 文档对比新旧模型的参数差异：docs.apiyi.com。

Q2：gpt-image-2 接入官方 API 调用为什么经常超时？

high 画质 + 2K/4K 单张图实测耗时 3-5 分钟。如果客户端默认超时是 60 秒，必然失败。修复方案：把 timeout 设到 360-600 秒。Python SDK 用 OpenAI(timeout=600)，Node.js 用 timeout: 600_000，cURL 用 --max-time 600。

Q3：gpt-image-2 接入官方 API 返回的 b64_json 怎么直接显示在网页上？

API 返回的是纯 base64 字符串无前缀，浏览器无法直接渲染。需要拼接：

const dataUri = `data:image/${format};base64,${b64}`;
imgElement.src = dataUri;

如果是后端服务，建议把 base64 解码后保存到 OSS/CDN，前端只接收 URL，避免 base64 字符串塞满 HTML 影响首屏速度。我们建议通过 API易 apiyi.com 平台测试时优先用 cURL + base64 解码到本地文件验证，确认链路通畅后再接入完整的存储分发架构。

Q4：gpt-image-2 接入官方 API 时透明背景能做吗？

目前 gpt-image-2 不支持透明背景，传 background: "transparent" 会被 400 拒绝。变通方案：生成纯白/纯绿背景图后，用客户端工具（如 rembg 库）抠图获得透明背景。

Q5：gpt-image-2 接入官方 API 的 thinking 参数怎么用？

thinking 是 gpt-image-2 引入的推理参数（off / low / medium / high），开启后模型会先做布局规划再生成，质量更高但成本会显著上升（high 模式成本约 4-5 倍基础值）。建议：只在文字密集型海报、复杂构图场景使用 medium，常规场景保持 off。我们建议通过 API易 apiyi.com 的统一接口先做 A/B 测试，再决定是否长期开启。

Q6：gpt-image-2 接入官方 API 时遇到 403 内容审核怎么办？

先尝试在请求里加 moderation: "low" 降低敏感度。如果仍被拦截，说明 prompt 触发了核心安全策略（涉及暴力、未成年人不当内容、知名人物肖像等），需要重写 prompt。注意：moderation: "low" 不是关闭审核，只是放宽，仍会拦截高危内容。

Q7：gpt-image-2 接入官方 API 的 base_url 写错会怎样？

如果写成 https://api.apiyi.com（少了 /v1），SDK 会拼成 api.apiyi.com/images/generations 导致 404。正确写法是 https://api.apiyi.com/v1。Python 用 base_url，Node.js 用 baseURL（驼峰），别搞错大小写。

Q8：gpt-image-2 接入官方 API 多图融合的最佳实践是什么？

最多 16 张参考图，prompt 里用「图1/图2」指代。关键技巧：

  1. 第一张参考图通常作为「主体」，模型会优先保留其结构
  2. 复杂指令可分步：先写「以图1为主体」，再写「融合图2 的色调」
  3. 多图编辑成本是文生图的 1.5-2 倍，预算敏感场景慎用
  4. 建议先用 2-3 张图跑通逻辑，再扩展到更多参考图

总结：gpt-image-2 接入官方 API 的完整路径回顾

走完本文 9 个章节，你应该已经掌握了 gpt-image-2 接入官方 API 的完整工程方法：

  1. ✅ 准备工作 —— SDK 升级到最新、超时设到 ≥ 360 秒
  2. ✅ base_url 配置 —— 替换为 https://api.apiyi.com/v1，其他代码与官方一致
  3. ✅ 文生图调用 —— Python/Node.js/cURL 三语言模板
  4. ✅ 参数详解 —— size 8 种预设 + 自定义、quality 三档、output_format 三选
  5. ✅ 图片编辑 —— 最多 16 张参考图、prompt 用「图1/图2」指代
  6. ✅ Inpainting 重绘 —— mask alpha 通道，透明区域重绘
  7. ✅ 错误处理 —— 400/401/403/429/5xx 完整应对方案
  8. ✅ 生产实践 —— 指数退避、并发控制、成本预估、可观测性

最后给一个落地建议：先用 low 画质 + 1024×1024 跑通一次 hello world，再逐步加复杂度。这样能快速发现 SDK 版本、超时、API Key 等基础问题，避免一上来就在 high + 4K 的长尾请求里浪费调试时间。

如果你的团队正准备评估 gpt-image-2 接入方案、或者已经在写第一版代码遇到参数报错、超时等问题，建议直接通过 API易 apiyi.com 申请测试 Key 跑一遍本文的代码模板。所有示例都基于官方 SDK + APIYI 官转通道（字段 100% 一致），通用性极高，能直接复用到你自己的项目。

参考资料

  1. OpenAI gpt-image-2 模型文档：模型能力、参数、定价权威说明

    • 链接: developers.openai.com/api/docs/models/gpt-image-2
    • 说明: 包含 4K 渲染、字符级文字、推理整合等核心特性

  2. OpenAI Image Generation 指南：文生图、编辑、inpainting 完整工作流

    • 链接: developers.openai.com/api/docs/guides/image-generation
    • 说明: 涵盖 size/quality/format 全部参数详解

  3. OpenAI Create Image API Reference：/v1/images/generations 端点完整字段

    • 链接: developers.openai.com/api/reference/resources/images/methods/generate
    • 说明: 请求/响应字段权威参考

  4. APIYI 官方接入文档：gpt-image-2 中文版完整接入指南

    • 链接: docs.apiyi.com/api-capabilities/gpt-image-2/overview
    • 说明: 含 cURL/Python/Node.js 示例和错误码处理

  5. OpenAI Cookbook · Rate Limits：429 错误的指数退避方案

    • 链接: developers.openai.com/cookbook/examples/how_to_handle_rate_limits
    • 说明: 官方推荐的限流处理代码模板

作者: APIYI 技术团队
发布日期: 2026 年 4 月 27 日
关键词: gpt-image-2 接入官方 API、base_url、文生图、图片编辑、inpainting、APIYI、OpenAI SDK

发表评论