OpenAI API图片生成与编辑完整教程

时间：2026-07-22 14:34

返回成功但缺图，常因未解码b64_json。编辑接口注意蒙版尺寸、格式及透明通道。单次用ImageAPI，多轮用ResponsesAPI。密钥通过环境变量传入，避免硬编码。生成需明确尺寸、质量、格式；编辑参考图二进制提交，蒙版含alpha且与原图一致。错误处理区分权限、限流、参数与内容问题。

调用接口返回成功，但在目录中始终找不到生成的图片？这通常并非模型未能完成绘制，而是代码遗漏了将 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；当遇到权限报错时，应首先检查组织状态，而非反复更换模型名称。

OpenAI 图片生成官方文档总览显示 gpt-image-2 以及 Generations 和 Edits 两类入口

在总览页面中，可以看到两项核心能力：Generations 用于从提示词新建图片，Edits 用于修改现有图片或使用参考图。首先明确您的任务属于哪一类，再据此编写请求。

将 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 后若仍在旧终端测试，可能无法读取到新值。
安装 SDK 并建立独立的输出目录。

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

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

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

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

生成第一张图：请求成功后务必保存 Base64 数据

使用 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，不要直接取下标。

OpenAI 官方文档的 Generate Images 段落与 Python 生成图片代码入口

Generate Images 段落同时提供了 Image API 和 Responses API 两条路线。新手建议先保持 Image API 选项，确认生成、解码、落盘三个步骤均能正常完成，再考虑引入多轮上下文。

尺寸、质量与文件格式需同步确定

根据用途设置输出参数。

入口位置：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" 参数，当前模型不支持该选项。
选择合适的输出格式与压缩率。

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

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

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

失败处理：JPEG 或 WebP 无法打开时，请核对输出扩展名和格式参数是否匹配；压缩参数仅适用于 JPEG 与 WebP，不要将其作为 PNG 的通用选项使用。

OpenAI 官方文档显示 gpt-image-2 的尺寸质量格式压缩和背景选项

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

使用参考图编辑时，切勿将输入文件当作普通文本参数

将参考图作为二进制文件传递给 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；请勿通过添加该参数来解决构图偏差。

OpenAI 官方文档的 Edit Images 段落列出参考图生成和蒙版局部编辑能力

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

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

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

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

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

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

失败处理：尺寸或格式错误时，先统一画布再导出为 PNG；如果只有黑白像素但没有 alpha 通道，需要将灰度信息写入 alpha 通道后再提交。
连同原图、蒙版和新提示词发起编辑请求。

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

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

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

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

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

使用图片生成工具保留多轮上下文。

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

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

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

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

将失败原因归为权限、限流、参数和内容四类

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

入口位置：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。
四张官方文档截图均能正常打开，分别对应接口选择、生成入口、编辑能力和输出参数。

来源：codex?UpFNUF8Z4

OpenAI

上一篇如何创建Hugging Face Hub模型仓库教程 下一篇ComfyUI模型类型目录与加载方式科普

本站内容用于信息整理与展示，如有侵权或内容问题请及时联系处理。