AI 图片编辑接口报 400 怎么排查？先读错误体，再查参数、图片与 mask

图片编辑接口返回 400，不要先把原图转成 PNG，也不要立刻压缩。第一步应读取结构化错误体中的 code、type、param 和 message，确认它指向模型、字段、图片解码、mask 还是请求体积。随后固定模型、端点和输入，用最小请求做单变量对照，才能避免把一次偶然成功写成根因。

本文讲通用排障方法，并以 OpenAI Images API 的 gpt-image-2 为当前参数示例。示例事实查阅于 2026-08-03；其他模型、Responses image tool、Gemini GenerateContent 和第三方兼容端点必须分别核对，不能混用字段。

第一步不是处理图片，而是按错误体分流

HTTP 400 是结果，不是根因。先完整保存响应状态、响应头和脱敏错误体，再按下面的线索决定下一步：

错误体或响应特征	优先检查	暂时不要做
unknown_parameter、unsupported parameter，或 param 明确指向字段	模型、端点与字段支持矩阵	反复转码原图
invalid_image、invalid_image_file、decode 失败	文件签名、MIME、完整解码、输入格式	先调输出质量或尺寸
错误指向 mask	mask 尺寸、实际格式、alpha 语义和字段名	只检查原图
request too large、payload too large，或小图成功而多图失败	最终 HTTP 请求体及各层上限	只统计磁盘文件总量
错误指向 model、size、background、input_fidelity 等	当前模型的接口参考	套用另一模型的示例
返回 HTML、空响应或无法解析的错误	代理、网关、错误映射和实际响应层	假定错误来自模型服务

结构化错误字段的名称取决于服务实现，兼容网关也可能改写错误格式。如果错误体已经明确指向某个参数，先在其他条件不变时删除或修正该参数；图片标准化应该留到文件类线索出现之后。

先锁定四件事：协议、端点、模型、请求类型

"AI 图片接口"至少可能指下面几类完全不同的调用：

请求类型	典型输入	排障重点
纯文生图	提示词	模型、端点、输出参数和权限
图片编辑	原图和提示词	除参数外，检查文件、multipart 和编辑能力
局部重绘	原图、mask 和提示词	增加 mask 格式、尺寸及 alpha 检查
参考图生图	一张或多张参考图	图片数量、顺序、总量和模型支持范围

还要确认调用的是 OpenAI Images API、Responses API 的 image generation tool、Gemini GenerateContent，还是其他厂商的原生协议。路径、请求结构、图片输入方式和字段名都可能不同。即使同一厂商的两套 API 能完成相似任务，也不能直接复制参数。

每次实验应记录：

SDK 与版本
Base URL 和最终 endpoint
模型完整 ID
请求类型与输入方式
唯一改动项
HTTP 状态和脱敏 code/type/param/message

建立一个已知条件下的最小请求

准备一张自己生成、没有敏感内容、能够完整解码的小型 RGB PNG。图片编辑请求只保留目标端点要求的模型、提示词和一张图片，先不带 mask、输出格式、透明背景、质量、多图和其他可选字段。

下面是 OpenAI Python SDK 的 Images API 结构示例。模型通过环境变量提供，是为了提醒读者使用目标端点当前明确支持编辑的模型，而不是把示例值当成兼容端点的保证：

import os
from importlib.metadata import version

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL"),
)


def minimal_edit(image_path: str):
    print({
        "sdk": "openai",
        "sdk_version": version("openai"),
        "model": os.environ["IMAGE_MODEL_ID"],
        "test": "minimal_image_edit",
    })

    with open(image_path, "rb") as image_file:
        return client.images.edit(
            model=os.environ["IMAGE_MODEL_ID"],
            image=image_file,
            prompt="保留主体，只把背景改成浅灰色",
        )

这个模板用于控制变量，不代表所有兼容端点都支持相同 SDK 方法。最小请求仍失败时，先核对模型 ID、最终 /v1/images/edits 端点、鉴权、文件内容以及错误体；基线成功后，才逐项恢复可选字段或替换成业务图片。

建立"模型 + 端点 + 字段"矩阵

图片参数变化快，不能只记"某厂商支持什么"。应记录到具体模型和端点：

模型与端点	当前字段事实	排障时怎么用
gpt-image-2 + Images API	默认返回 Base64 图片；output_format 可选择 PNG、JPEG 或 WebP	不要为它复用旧模型的 response_format 示例
gpt-image-2 + Images API 编辑	input_fidelity 应省略，模型自动按其当前方式处理输入	错误指向该字段时，不要强行设置某个值
gpt-image-2 输出	当前不支持透明输出背景	不要把 background="transparent" 当作通用编辑参数
DALL·E 旧模型 + 对应 Images API	response_format 属于旧模型兼容行为	必须按具体模型生命周期和 API 参考核对

上述 gpt-image-2 事实来自 OpenAI Image generation 指南及 Images API 参考（查阅日期：2026-08-03）。模型行为会变化，发布或执行测试前仍应重新核对。

不要把 Gemini 的 thinkingConfig 放进 OpenAI Images 请求，也不要把 OpenAI 的图片字段移植到 Gemini GenerateContent。Google 的 schema 同时存在 thinkingLevel 和 thinkingBudget，具体适用性取决于模型系列与版本；这不是图片文件排障的通用步骤。若错误明确指向 thinking 字段，再查 Google GenerateContent 参考和目标模型的 Thinking 指南（查阅日期：2026-08-03）。

文件检查：扩展名、MIME 和真实内容要一致

把 photo.heic 改名为 photo.jpg 不会改变文件编码；手写 image/png 也不会把 JPEG 重新编码为 PNG。可以先用 Pillow 完整解码，并记录实际格式：

from pathlib import Path

from PIL import Image


def inspect_image(path: str) -> dict:
    file_path = Path(path)
    with Image.open(file_path) as img:
        img.load()
        result = {
            "suffix": file_path.suffix.lower(),
            "detected_format": img.format,
            "mode": img.mode,
            "width": img.width,
            "height": img.height,
            "has_alpha": "A" in img.getbands() or "transparency" in img.info,
            "has_icc": bool(img.info.get("icc_profile")),
            "has_exif": bool(img.getexif()),
            "bytes": file_path.stat().st_size,
        }
    return result

img.load() 会读取全部像素，比只检查文件头更适合发现截断或解码问题。但 Pillow 可以读取，不等于目标端点一定支持；它也不能证明 SDK 最终为 multipart part 声明了正确 MIME。后者应在 HTTP 客户端发送前的观测点或受控代理中核对。

标准化副本只能做兼容性对照

手机照片、设计软件导出图和旧素材可能带 EXIF 方向、ICC 配置或 CMYK 色彩。排障时可以制作不覆盖原件的副本：

from PIL import Image, ImageOps


def normalize_for_test(src: str, dst: str) -> None:
    with Image.open(src) as img:
        img.load()
        transposed = ImageOps.exif_transpose(img)
        has_alpha = "A" in transposed.getbands() or "transparency" in transposed.info
        normalized = transposed.convert("RGBA" if has_alpha else "RGB")
        normalized.save(dst, format="PNG")

这一步同时改变方向、色彩模式、元数据、编码和文件体积。原图失败而副本成功，只能说明这些变化中的至少一项与故障有关；要确认具体根因，还需分别控制 EXIF、ICC、色彩模式和编码。CMYK 转 RGB 也不等于完成专业色彩管理，JPEG 转 PNG 还可能增大文件，不能用同一个副本同时证明体积问题。

图片编辑专项：mask 要单独检查

带 mask 的编辑请求应先证明"不带 mask 的同一原图"能够成功，再加入 mask。至少检查：

• 原图和 mask 的像素尺寸是否一致；
• 两者是否满足当前端点要求的实际文件格式，而不只是后缀一致；
• mask 是否真的包含 alpha 通道；
• alpha 的透明/不透明区域是否符合该接口定义的编辑语义；
• SDK 字段名和 multipart part 名是否与当前端点一致；
• 所用模型和端点是否支持 mask 编辑。

可以用下面的代码先做本地结构检查：

from PIL import Image


def inspect_mask(image_path: str, mask_path: str) -> dict:
    with Image.open(image_path) as image, Image.open(mask_path) as mask:
        image.load()
        mask.load()

        mask_has_alpha = (
            "A" in mask.getbands() or "transparency" in mask.info
        )
        return {
            "same_pixel_size": image.size == mask.size,
            "image_format": image.format,
            "mask_format": mask.format,
            "same_detected_format": image.format == mask.format,
            "mask_mode": mask.mode,
            "mask_has_alpha": mask_has_alpha,
        }

对当前 OpenAI mask 编辑文档，原图与 mask 需满足相同格式和尺寸要求，mask 需要 alpha 通道；具体限制见 Image generation 指南（查阅日期：2026-08-03）。其他端点可能采用不同的遮罩语义，不能照搬。

三种"透明"不要混为一谈

概念	作用	可能导致的误判
输入原图的 alpha 通道	描述输入像素透明度	原图带 alpha 不代表输出必须透明
mask 的 alpha 通道	表达哪些区域参与编辑	mask 有 alpha 不代表其方向和语义正确
输出透明背景	请求生成结果具有透明背景	取决于模型支持；当前 gpt-image-2 不支持

因此，"透明通道符合预期"不是一个足够精确的检查项。必须写清是在检查输入图、mask，还是输出参数。

体积检查：磁盘文件总量不等于 HTTP 请求体

图片请求可能使用 multipart、Base64 JSON、URL 或文件引用。这些口径不能互换：

输入方式	应测什么	常见遗漏
multipart	最终编码后的 HTTP body	boundary、字段头、文件头和其他表单字段开销
Base64 JSON	最终序列化并实际发送的 JSON 字节	Base64 膨胀、转义和其他字段
URL	URL 请求本身及服务端抓取结果	过期、权限、重定向、MIME 和抓取上限
文件引用	上传阶段和引用阶段分别观测	文件 ID 作用域、过期和目标模型支持

原文件总量只能说明素材在磁盘上的大小，不是 multipart body。要测最终请求体，应在 SDK 或 HTTP 客户端编码完成、发送之前观测，或使用已获授权的受控代理；若使用分块传输，也不能只依赖 Content-Length。

Base64 JSON 可以对"实际将要发送的同一份序列化结果"计数：

import json


def json_body_size(payload: dict) -> int:
    body = json.dumps(
        payload,
        ensure_ascii=False,
        separators=(",", ":"),
    ).encode("utf-8")
    return len(body)

如果 SDK 重新序列化、压缩或改用 multipart，这个数字就不代表最终请求。小图成功、大图失败也只能提示体积相关；还要结合实际请求体和链路日志，才能确认是哪一层的限制。

什么时候可以把线索写成根因？

至少需要形成下面的证据闭环：

1. 相同模型、端点、SDK 版本和输入能够重复失败；
2. 一次只改变一个条件后能够重复成功；
3. 恢复该条件后再次失败；
4. 错误体或可用日志与变化方向一致；
5. 修复后完成真实图片编辑并得到可解析结果，而不只看到 HTTP 200。

标准化副本成功、删除参数后成功或换小图成功，都只是方向性证据。拿不到服务端日志时，可以写"对照结果指向某字段或某类文件内容"，不要虚构具体内部实现。

附录：经过第三方兼容平台时怎样提交证据

第三方平台能协助对齐入口时间、状态和关联记录，但不能替代客户端请求体检查，也不应被描述为"换个平台就能解决 400"。如果请求经过 147AI，可将其作为独立测试入口和记录核对渠道；具体可见字段与支持流程以当前账号页面和147AI的API接口文档为准。

提交支持前整理：

• 精确到秒的报错时间和时区；
• SDK、版本、脱敏 Base URL 结构及最终 endpoint；
• 模型完整 ID、请求类型和输入方式；
• 图片与 mask 的实际格式、像素尺寸、alpha 状态和文件字节数；
• 脱敏后的 HTTP 状态、code、type、param 和错误摘要；
• 最小请求结果，以及唯一改变哪个字段或文件后结果发生变化；
• 必要的关联标识仅通过受控私密渠道提交。

不要在公开帖子、文章评论或普通群聊中发送 API Key、完整 Base64、原始敏感图片、完整提示词、带签名参数的私有 URL、真实 Base URL、完整请求体或关联标识。

最终检查清单

• 已先读取并脱敏保存错误体，而不是直接处理图片
• 已确认协议、最终端点、模型和请求类型
• 已建立不带可选参数和 mask 的最小成功请求
• 所有可选字段均来自当前模型和端点文档
• 扩展名、文件签名、解码格式和上传 MIME 已分别核对
• 标准化副本只用于兼容性对照，没有被当成单一根因证明
• mask 与原图的尺寸、格式、alpha 和接口语义已经核对
• 已区分输入 alpha、mask alpha 和输出透明背景
• 原文件总量与 multipart、Base64 JSON、URL 或文件引用口径分开记录
• 修复结论来自可重复的单变量回归和端到端编辑结果

排查图片编辑接口的 400，顺序比工具更多更重要：先让错误体决定方向，再固定协议、端点和模型；建立最小请求后，依次恢复参数、业务图片、mask 和更大的输入。这样即使没有上游内部日志，也能把字段错误、文件问题、遮罩问题和传输限制逐层分开。