展开本页目录
开始前准备什么
- 保留请求时间、准确型号、接口、参数与脱敏错误正文。
- 保留原图和已有响应，不删除成功文件或任务 manifest。
- 在模型广场核对自己的令牌权限与当前通道可用的编辑接口。
- 定位环节
- 核对请求
- 检查响应
- 恢复文件
- 验收画面
按任务记录尺寸、主体、标签、文字、视觉验收与实际费用，避免只看 HTTP 成功。
先核对已有文件、缓存与 manifest，再决定是否显式重发。
先选症状，按对应环节排查
HTTP 状态码只是线索，要结合真实错误正文与调用记录判断原因。下方保留了一张背景编辑实测的尺寸与视觉边界，可用来理解文件返回成功与参数验收的区别。
| 症状 | 先检查 | 是否立即重发 |
|---|---|---|
| 文件找不到、不是有效 PNG | 本地路径、权限、文件签名与尺寸 | 修复本地素材后再提交 |
| 接口返回 HTTP 错误 | 真实错误正文、权限、接口、参数与通道 | 先核对原因及记录，不盲目重试 |
| 超时、连接中断 | 请求是否已发出、控制台记录、缓存响应 | 先确认远程处理情况 |
| HTTP 成功，但未保存图片 | data、b64_json、返回格式、磁盘权限 | 优先解码已有结果，不重复生成 |
| 能打开但尺寸或画面不符 | 实收尺寸、参数透传、主体与文字验收 | 按实际不符项调整，不算请求错误 |
- 症状
- 文件找不到、不是有效 PNG
- 先检查
- 本地路径、权限、文件签名与尺寸
- 是否立即重发
- 修复本地素材后再提交
- 症状
- 接口返回 HTTP 错误
- 先检查
- 真实错误正文、权限、接口、参数与通道
- 是否立即重发
- 先核对原因及记录，不盲目重试
- 症状
- 超时、连接中断
- 先检查
- 请求是否已发出、控制台记录、缓存响应
- 是否立即重发
- 先确认远程处理情况
- 症状
- HTTP 成功，但未保存图片
- 先检查
- data、b64_json、返回格式、磁盘权限
- 是否立即重发
- 优先解码已有结果，不重复生成
- 症状
- 能打开但尺寸或画面不符
- 先检查
- 实收尺寸、参数透传、主体与文字验收
- 是否立即重发
- 按实际不符项调整，不算请求错误
上传检查：接口路径与 multipart 必须匹配
编辑本地图片使用 POST /v1/images/edits；不要把编辑参数发到 Chat Completions，或把本地文件路径写成远程图片 URL。用 curl -F 时让 curl 自动生成 Content-Type 和 boundary，手动覆盖可能导致服务端无法解析文件。
- 先确认 input.png 的真实内容与路径；改扩展名不会转换图片格式。
- 查看当前型号与通道支持的参数，不直接复制 2.5 型号的质量档位。
- GPT Image 2 不要手动设置 input_fidelity；按其官方型号说明与当前通道验收。
- 排查时不使用 curl -v 导出认证请求头；分享文件前去除密钥、用户图片链接与敏感正文。
请求结构示意；确认权限、参数和费用后才执行
curl --fail-with-body --max-time 180 \
https://api.apizt.com/v1/images/edits \
-H "Authorization: Bearer $tokenba_API_KEY" \
-F model=gpt-image-2 \
-F 'image=@./input.png' \
-F 'prompt=Keep the subject unchanged. Replace only the background with a cream studio wall. No text.' \
-F n=1 -F size=1024x1024 -F quality=low \
-o edit-response.json
本站绘制的内容说明图：此页最小编辑请求用表单文件，不手写 JSON 图片字段或 multipart boundary；参数仍按实际通道核对。
响应检查：看结构，不能把 JSON 直接改名为 PNG
Images 的返回图片通常位于 data 数组。GPT Image 官方返回 base64 图片时，应解码 b64_json，再检查文件签名、完整解码与实际宽高。usage 是返回用量，不能替代控制台账单。
apizt 不同通道的返回格式需要实际核对。批量下载脚本只接受 PNG 的 b64_json，不获取 URL；若通道返回别的结构，会保留不确定状态并停止，而不是把它当成功图片。
返回结构示意，不是错误或实测响应
{
"data": [{ "b64_json": "BASE64_IMAGE_BYTES" }],
"usage": { "input_tokens": 0, "output_tokens": 0 }
}超时与中断：先恢复本次结果，再考虑新增请求
- 记录时间、型号、任务 ID 与可用请求标识，查控制台调用记录和实际用量。
- 已收到响应但保存失败时，从原响应解码或从缓存恢复；不重新请求模型。
- 本地超时不证明服务端取消。没有明确取消或查询能力时，保持状态未确定。
- 确认没有可恢复结果后再选择重发，接受可能产生第二次费用；不要无限循环重试。
真实观察：请求 1024×1024，实际收到 1254×1254
既有背景编辑请求使用 gpt-image-2、size=1024x1024、quality=low，原图为 1254×1254。返回 PNG 实际同样是 1254×1254。任务成功返回文件，但这份记录不足以证明尺寸参数被通道按要求处理。
先读实际 PNG 宽高，再与原图及请求参数对照；保留样例给通道核对。不要只按请求的 size 标注交付尺寸，也不能把这一次现象推广为所有请求都忽略 size。
| 记录项 | 既有实测值 |
|---|---|
| 请求 size / quality | 1024x1024 / low |
| 原图 / 实收 PNG | 1254×1254 / 1254×1254 |
| 返回输入 / 输出用量 | 814 / 765 tokens |
| 视觉检查 | 单张背景改变，可见鲸鱼细节保留；不是像素一致性保证 |
| 实际扣费 | 尚未核实；不标免费 |
- 记录项
- 请求 size / quality
- 既有实测值
- 1024x1024 / low
- 记录项
- 原图 / 实收 PNG
- 既有实测值
- 1254×1254 / 1254×1254
- 记录项
- 返回输入 / 输出用量
- 既有实测值
- 814 / 765 tokens
- 记录项
- 视觉检查
- 既有实测值
- 单张背景改变，可见鲸鱼细节保留；不是像素一致性保证
- 记录项
- 实际扣费
- 既有实测值
- 尚未核实；不标免费
保留本页真实换背景结果；返回图宽高不等于请求 size，此例不能作为严格尺寸控制或通用报价证明。
没有报错，但商品或中文不对：这是验收不通过
图像生成模型仍可能改变品牌元素、标签、细节或文字位置。把问题写成具体差异：哪个 SKU、哪段文字、哪个结构、哪块区域不符合要求；不要只写“效果不好”。
商品本体要求精确保留时，使用真实商品图层合成背景。中文价格、日期、Logo 与二维码要求准确时，用确定性排版放入。这些环节分别验收，不能把 HTTP 成功当作交付完成。
准备一份可核对的排查材料
| 应保留 | 处理方式 |
|---|---|
| 时间、准确模型、接口、参数 | 使用实际值，避免把型号别名当准确 ID |
| HTTP 状态与真实错误正文 | 脱敏后保留原文，不凭状态码改写成另一种原因 |
| 原图与输出尺寸、文件摘要 | 使用可共享的小样，移除客户敏感素材 |
| 响应结构、usage、控制台记录 | 区分返回用量、实扣、文件保存与视觉验收 |
| 任务状态与恢复尝试 | 说明有无重复提交，保留原 manifest |
- 应保留
- 时间、准确模型、接口、参数
- 处理方式
- 使用实际值，避免把型号别名当准确 ID
- 应保留
- HTTP 状态与真实错误正文
- 处理方式
- 脱敏后保留原文，不凭状态码改写成另一种原因
- 应保留
- 原图与输出尺寸、文件摘要
- 处理方式
- 使用可共享的小样，移除客户敏感素材
- 应保留
- 响应结构、usage、控制台记录
- 处理方式
- 区分返回用量、实扣、文件保存与视觉验收
- 应保留
- 任务状态与恢复尝试
- 处理方式
- 说明有无重复提交，保留原 manifest
怎样确认已经完成
- 定位上传、接口、落盘或视觉验收环节。
- 保留真实脱敏错误与请求信息。
- 超时与保存失败先恢复结果，不盲目重发。
- 实收尺寸、视觉结果与实际费用分别核对。
常见问题
HTTP 200 为什么还没有可用图片？
可能只拿到了 JSON 响应，尚未解码或保存，也可能返回格式与客户端预期不同。核对 data、b64_json 和文件内容，确认能完整打开，再进行视觉验收。
超时是不是不会扣费？
不能这样判断。远程服务可能已收到或处理请求；先查调用记录和可恢复结果，再决定是否重新提交。
实收尺寸不等于 size，一定是模型错误吗？
不一定。需要核对原图、官方参数、当前通道的转换与透传。本站只记录过一个请求 1024×1024、实收 1254×1254 的样例，没有证据把原因统一归到模型或所有通道。