调用返回成功，目录里却没有图片，通常不是模型没画出来，而是代码忘了把 b64_json 解码并写入文件。编辑接口更容易多出第二个坑：参考图、蒙版和提示词都提交了，但蒙版尺寸、格式或透明通道不合要求。OpenAI 图片 API 当前指南把单次生成与编辑放在 Image API，把连续多轮修改放在 Responses API；第一次接入时先走 Image API，验证链路最短。

先选对接口，再准备密钥和 Python 环境

当前官方页面把 gpt-image-2 标为最新 GPT Image 模型。只需要根据一段提示词生成一张图，或拿现有图片做一次编辑，直接使用 Image API；需要在对话里反复改图、保留前一轮上下文，才使用带 image_generation 工具的 Responses API。部分组织在调用 GPT Image 前可能需要完成 API Organization Verification，权限报错时应先检查组织状态，不要反复更换模型名称。

看总览里的两项能力：Generations 从提示词新建图片，Edits 修改现有图片或使用参考图。先确定任务属于哪一项，再写请求。

1. 把 API 密钥放进环境变量。

   入口位置：OpenAI API Dashboard 的 API Keys 页面，以及本机终端。

   主要动作：创建项目密钥后，只在本机环境变量中保存。macOS 或 Linux 当前终端执行 export OPENAI_API_KEY="你的密钥"；Windows PowerShell 可执行 setx OPENAI_API_KEY "你的密钥"，随后新开一个 PowerShell 窗口。不要把真实密钥写进 Python 文件、截图或版本库。

   成功标志：Python 创建 OpenAI() 客户端时不需要再传入明文密钥，SDK 能从环境读取。

   失败处理：出现 401 时，先检查环境变量是否存在、是否带了多余引号或空格、密钥是否属于当前项目；Windows 使用 setx 后仍在旧终端测试，也会读不到新值。

2. 安装 SDK 并建立独立输出目录。

   入口位置：项目根目录的终端。

   主要动作：运行 python -m pip install --upgrade openai，再创建 outputs 文件夹。项目中不要使用名为 openai.py 的文件，避免覆盖 SDK 包名。

   成功标志：运行 python -c "from openai import OpenAI; print('ok')" 输出 ok。

   失败处理：若提示找不到模块，确认安装命令和运行脚本使用的是同一个 Python；虚拟环境项目应先激活环境，再重新安装。

生成第一张图：请求成功后还要保存 Base64

3. 用 images.generate 发起单次生成。

   入口位置：项目中新建 generate_image.py。

   主要动作：把提示词写清主体、环境、构图和视觉限制，调用 client.images.generate，再读取返回数组第一项的 b64_json。

   from pathlib import Path
   import base64
   from openai import OpenAI
   
   client = OpenAI()
   result = client.images.generate(
       model="gpt-image-2",
       prompt=(
           "A clean editorial still life of a ceramic cup beside a notebook, "
           "soft morning window light, no text, no logo"
       ),
       size="1024x1024",
       quality="low",
   )
   
   output = Path("outputs/first-image.png")
   output.write_bytes(base64.b64decode(result.data[0].b64_json))
   print(output.resolve())

   成功标志：终端打印绝对路径，outputs/first-image.png 能被图片查看器正常打开且文件大小不为 0。

   失败处理：请求有返回但没有文件时，检查是否执行了 Base64 解码与写文件；result.data 为空时先打印错误对象和请求 ID，不要直接取下标。

Generate Images 段落同时给出 Image API 和 Responses API 两条路线。新手先保持 Image API 选项，确认生成、解码、落盘三步都通，再考虑多轮上下文。

尺寸、质量和文件格式要一起决定

4. 按用途设置输出参数。

   入口位置：images.generate 或 images.edit 的参数列表。

   主要动作：草稿优先 quality="low"，成品再切到 medium 或 high。常用尺寸包括方形 1024x1024、横图 1536x1024 和竖图 1024x1536。gpt-image-2 还接受满足约束的自定义分辨率：最长边不超过 3840 像素，两条边都是 16 的倍数，长短边比例不超过 3:1，总像素位于 655360 到 8294400 之间。

   成功标志：输出像素与请求一致，草稿阶段延迟和成本可控，最终阶段再提高质量。

   失败处理：尺寸报错时先回到三个常用尺寸之一；需要透明背景时不要给 gpt-image-2 传 background="transparent"，当前模型不支持该选项。

5. 选择输出格式和压缩率。

   入口位置：同一请求的 output_format 与 output_compression 参数。

   主要动作：默认格式是 PNG；网页预览可选 JPEG 或 WebP，并用 0 到 100 的压缩参数控制文件体积。对延迟敏感时 JPEG 通常比 PNG 更快。

   成功标志：保存文件的扩展名与请求格式一致，浏览器或图片工具能正常解码。

   失败处理：JPEG 或 WebP 打不开时，核对输出扩展名和格式参数是否一致；压缩参数只用于 JPEG 与 WebP，不要把它当成 PNG 的通用选项。

这张页面要看两处：上方列出尺寸、质量、格式、压缩和背景选项；提示框明确说明 gpt-image-2 当前不接受透明背景。尺寸表还能用于排查自定义分辨率为什么被拒绝。

使用参考图编辑，不要把输入文件当成普通文本参数

6. 把参考图作为二进制文件交给 images.edit。

   入口位置：项目中新建 edit_image.py，并把 reference.png 放在同一目录。

   主要动作：以二进制读取参考图，提示词写明哪些元素必须保留、哪些元素需要改变。只有一张参考图时可直接传文件；多张参考图时传文件列表。

   from pathlib import Path
   import base64
   from openai import OpenAI
   
   client = OpenAI()
   with open("reference.png", "rb") as reference:
       result = client.images.edit(
           model="gpt-image-2",
           image=reference,
           prompt=(
               "Keep the cup shape and camera angle. Change the table to dark oak, "
               "add soft evening light, no text, no logo."
           ),
           size="1024x1024",
           quality="low",
       )
   
   Path("outputs/edited-image.png").write_bytes(
       base64.b64decode(result.data[0].b64_json)
   )

   成功标志：edited-image.png 保留提示词要求的参考图特征，同时完成指定改动。

   失败处理：细节丢失时先缩小改动范围并明确保留项。gpt-image-2 会以高保真方式处理输入图，不接受自定义 input_fidelity；不要靠添加该参数解决构图偏差。

Edit Images 段落列出三种任务：修改现有图片、使用一张或多张参考图生成新图、上传蒙版指定替换区域。先确认自己的目标属于哪一类，提示词才不会同时要求“完全保留”和“彻底重画”。

局部修改时，蒙版必须满足文件约束

7. 为首张输入图准备带透明通道的蒙版。

   入口位置：图片编辑工具的画布设置，或 Python 图像处理脚本。

   主要动作：让原图与蒙版采用相同格式和相同尺寸，单个文件小于 50MB；蒙版必须含 alpha 通道。多参考图请求中，蒙版只应用到第一张输入图。

   成功标志：蒙版文件能以 RGBA 打开，宽高与第一张输入图完全一致。

   失败处理：尺寸或格式错误时先统一画布再导出 PNG；只有黑白像素但没有 alpha 通道时，需要把灰度信息写入 alpha 通道后再提交。

8. 连同原图、蒙版和新提示词发起编辑。

   入口位置：client.images.edit 的 image、mask 和 prompt 参数。

   主要动作：以二进制方式分别打开原图与蒙版，提示词描述最终完整画面，不要只写被替换区域的单个名词。

   成功标志：指定区域发生变化，未指定区域大体保持；结果文件可正常解码。

   失败处理：蒙版边界没有被精确遵守不一定是接口错误。GPT Image 把蒙版作为提示引导，无法保证逐像素贴合；收窄提示词、留出更清晰的蒙版范围后再生成。

需要连续改图时，再换到 Responses API

9. 用图片生成工具保存多轮上下文。

   入口位置：client.responses.create 的 tools 参数。

   主要动作：首轮传入 tools=[{"type": "image_generation"}]；第二轮通过 previous_response_id 连接上一轮，再提交新的修改要求。action 保持 auto 时由模型决定生成或编辑，也可设为 generate；只有上下文里已有图片时才强制 edit。

   成功标志：响应输出包含 image_generation_call，后续轮次在上一张图的基础上变化。

   失败处理：没有图片上下文却强制 action="edit" 会返回错误；先完成一轮生成，或把 action 改回 auto。

把失败分成权限、限流、参数和内容四类

10. 根据状态码和错误代码决定是否重试。

    入口位置：SDK 异常对象、HTTP 状态码和响应里的请求 ID。

    主要动作：401 检查密钥、项目和组织；429 区分速率限制与额度耗尽；5xx 才使用带退避的短暂重试。图片参数或输入导致的 image_generation_user_error 不应原样自动重试，应先修改提示词、图片或参数。

    成功标志：日志能记录请求 ID、错误代码和调用阶段，重试只发生在短暂性故障上。

    失败处理：moderation_blocked 时先判断拦截发生在输入还是输出阶段，修改不合适的提示或输入图；不要通过无限重试消耗额度。

运行结果核对

• 真实密钥只存在于环境变量，没有进入脚本、截图或版本库。
• 已经根据单次任务或多轮任务选择 Image API 或 Responses API。
• 生成结果完成 Base64 解码，输出文件大小不为 0 且能正常打开。
• 尺寸、质量、格式和压缩参数彼此匹配，没有给 gpt-image-2 请求透明背景。
• 参考图通过二进制文件提交；蒙版与第一张输入图格式、尺寸一致并含 alpha 通道。
• 401、429、5xx 和图片输入错误采用不同处理路径，日志保留请求 ID。
• 四张官方文档截图均能打开，且分别证明接口选择、生成入口、编辑能力和输出参数。