图像生成与编辑 API

小白：先分清生成和编辑

从文字创建新图走 POST /v1/images/generations；带参考图、遮罩或局部修改走 POST /v1/images/edits。模型 ID、尺寸、质量、输出格式和可生成数量因模型与渠道而异，先在模型广场确认精确型号与端点。gpt-image-2 的文档介绍位于 OpenAI 图像能力页。本站的 /v1/images/variations 当前未实现。

最小文生图请求

先用单张、标准尺寸和低风险提示词验证协议。response_format 可请求 url 或 b64_json，但最终支持集合由模型与渠道决定。

Copycurl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只纸雕风格的白兔，在暖色工作室中",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

成功响应通常在 data[] 中返回 url 或 b64_json。不要把返回字段写死成只有一种；先检查数组长度，再按存在的字段分支处理。若本站将异步图像结果持久化，可按首次响应给出的请求标识查询 GET /v1/images/generations/result?request_id=...，不要自行猜测 ID。

参考图编辑与文件输入

multipart 编辑请求可以直接上传文件。限制文件类型、像素、字节数和数量，服务端接收后应流式转发；远程 URL 必须阻断内网、环回、云元数据地址和重定向绕过。

Copycurl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留主体构图，把背景改为雨夜霓虹街道" \
  -F "image=@input.png" \
  -F "response_format=url"

JSON 形式也可携带受支持的 URL、data URL 或 Base64 引用，但具体字段映射会随渠道变化。不要先调用 /v1/files：本站该 Files API 尚未实现。

错误、重试与结果生命周期

400 多为尺寸、格式、数量、参考图或模型能力不匹配；413 表示请求体过大；429 可能是限流、余额或并发约束；5xx 才可能适合有限重试。创建请求若超时，不能立刻无脑重发，否则可能重复计费和重复生成。保存 Request-ID、提示词哈希、模型、尺寸、质量和调用方幂等键，再判断是否查询已有结果。

返回 URL 可能有签名和有效期，生产系统应及时流式下载到自有对象存储，并记录内容类型、字节数、哈希、来源任务和删除时间。Base64 解码前先校验预计大小，避免同时在内存中保留 JSON、Base64 字符串和解码后的完整文件。

专家：质量、安全与成本治理

建立固定评测集覆盖文字渲染、人物一致性、品牌色、参考图忠实度、透明背景和敏感内容；模型升级时做盲测和灰度。把提示词、参考图和结果都视为敏感数据，应用内容审核、访问控制、保留期和删除流程。成本核算不能只看请求次数，还要记录模型、数量、尺寸、质量、输入图数量与重试；高并发服务应限制并行生成数、响应体大小和下载带宽，并在客户端断开后及时取消可取消的上游工作。