GPT-IMAGE-1 接入自动化设计工作流的接口配置与错误排查

把 GPT-IMAGE-1 接进自动化设计流程时，最常见的错误不是模型不适配，而是密钥没隔离、请求体字段不完整、以及日志里没有留下可判断的状态信息。下面这套配置与排查顺序，可以帮你从一次报错中分清楚是环境问题、参数问题还是服务端抖动。

集成 GPT-IMAGE-1 时，先按“密钥环境变量化 → 最小请求体 → 结果落盘 → 日志分类 → 超时重试”的顺序跑通。如果 4xx 报错，优先检查密钥和参数；5xx 报错尝试重试；网络异常则先确认出口连接。不要跳过日志直接改代码，状态码加响应文本能定位大部分问题。

初始化项目与密钥隔离

将密钥直接写在代码里，会污染自动化脚本和版本历史。建议在项目根目录创建 .env 文件，并把 .env 加入 .gitignore。

# .env
OPENAI_API_KEY=sk-your-key

然后在 Python 入口处读取。需要安装 python-dotenv。

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("OPENAI_API_KEY 未设置")

另一个推荐是把接口地址也放进去，避免在代码里改域名。读取后用一个配置对象统一管理，后续写请求和日志都用它。

构造图像生成请求体

不同服务商对 GPT-IMAGE-1 的字段定义会有差异，但稳定模型通常都接受模型名、提示词和图片尺寸。先按最小字段构造字典，再根据返回错误逐步补齐。

request_body = {
    "model": "gpt-image-1",        # 以官方文档为准
    "prompt": "a clean app icon for a design tool",
    "size": "1024x1024",           # 尺寸支持列表以官方文档为准
}

注意：不要上来就添加风格、种子等扩展字段。一些服务端对新增字段的校验很严格，多一个不支持的参数会让请求整体失败。先用最简结构请求，成功后再逐项叠加。

发送请求并处理响应

用 requests 发送 JSON 请求，并在响应中取出图片二进制。不同接口返回格式不同，可能是直接图片流，也可能 JSON 内嵌 base64。这里给出的是直接保存二进制流的写法。

import requests

url = os.getenv("GPT_IMAGE_API_URL")  # 接口地址从环境变量读取
headers = {
    "Authorization": f"Bearer {api_key}"
}

resp = requests.post(url, json=request_body, headers=headers, timeout=10)
resp.raise_for_status()

with open("output.png", "wb") as f:
    f.write(resp.content)

如果服务端返回的是 JSON，需要在写入前先取其中的图片字段。可以通过响应头 Content-Type 判断：如果包含 image/，直接取 content；如果是 application/json，则解码后取 base64 字段。不要假设所有接口都用同一种返回格式。

从日志定位请求失败原因

请求失败时，先打印 status_code 和 response.text，再根据范围归到网络、鉴权或参数校验。不要只看异常信息，很多服务端会把具体原因放在响应体里。

import traceback

try:
    resp = requests.post(url, json=request_body, headers=headers, timeout=10)
    print("status:", resp.status_code)
    print("body:", resp.text)
    resp.raise_for_status()
except requests.exceptions.Timeout:
    print("网络超时，检查本机到服务端连通性")
except requests.exceptions.RequestException as e:
    print("请求级错误，需要查看异常链")
    traceback.print_exc()

状态码分类时，可以按三条路径处理：

2xx 范围：请求被接受，问题在响应解析，检查字段名与编码。
4xx 范围：客户端问题，先查密钥权限、请求格式和参数校验错误。
5xx 范围：服务端问题，保留 request_id 并稍后重试。

如果响应体里包含 request_id 或 trace id，记到日志中，便于向服务商查询。

设置超时与重试机制

自动化任务不能无限等待。给请求设置连接和读取超时，并在遇到临时故障时重试。对于 4xx 错误不要重试，因为重试无法修复客户端问题；对于网络异常和 5xx，可以采用退避重试。

import time

max_attempts = 3
for attempt in range(max_attempts):
    try:
        resp = requests.post(url, json=request_body, headers=headers, timeout=(5, 15))
        if resp.status_code < 400:
            break
        elif resp.status_code < 500:
            print("客户端错误：不重试，立即退出")
            break
        else:
            print(f"服务端错误，第 {attempt+1} 次重试")
    except requests.exceptions.RequestException:
        print("网络异常，准备重试")

    time.sleep(2 * (attempt + 1))