OpenAI Images API 怎么用？

官方资料（2026-10-31 核对）：Image generation · Images and vision · Images API Reference · API Pricing · Deprecations

先选 API：生成、连续编辑还是图片理解？

Images API 是专用生成/编辑接口；Responses API 把图片生成纳入多轮上下文。Vision 则是“输入图片、输出理解结果”，不能与图片生成混成同一个计费和质量流程。若只是一次商品图、封面或局部编辑，专用 Image API 更直接；若用户会说“把上一张改成夜景，再去掉文字”，Responses API 更自然。

Sunburst、Flare 怎么选？

官方将 Sunburst 定位为更适合编辑精度的模型，将 Flare 定位为快速的日常高质量生成。模型选择不能只看一张“最好看的图”：至少准备相同提示词、相同参考图和相同参数的对照集，统计成功率、人工返工率、延迟和总成本。某些组织使用 GPT Image 前可能需要完成 API Organization Verification。

最小可用生成：服务端保存 Base64 图片

API Key 只能保存在服务端。下面示例直接调用 Image API，明确模型、尺寸、质量和输出格式；生产环境还要增加请求鉴权、配额、超时、重试、内容审核和对象存储。

import OpenAI from "openai";
import fs from "node:fs";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const result = await openai.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "极简产品摄影：白色桌面上的蓝色保温杯，柔和侧光，无文字",
  size: "1024x1024",
  quality: "high",
  output_format: "png",
  safety_identifier: stableHashedUserId
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync("product.png", Buffer.from(imageBase64, "base64"));

面向个人终端用户时，官方建议每次生成或编辑都发送稳定、保护隐私的 safety_identifier：可以对账号 ID 或邮箱做不可逆哈希，不要直接发送个人身份信息，且最长 128 个字符。旧 user 参数已弃用。

图片编辑：参考图、Mask 与提示词要一起设计

Images Edit API 当前可为 GPT Image 模型接收最多 16 张 PNG、WEBP 或 JPG 参考图，每张小于 50 MB。多参考图适合商品组合、角色一致性和风格参考，但输入越多，成本、延迟和冲突也可能增加。必须记录每张图的用途和顺序，不要把任意用户图片直接拼入请求。

const result = await openai.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [
    fs.createReadStream("product.png"),
    fs.createReadStream("style-reference.jpg")
  ],
  prompt: "保留第一张图的杯身形状和蓝色；只改成第二张图的柔和棚拍风格；不要添加文字",
  quality: "high",
  output_format: "webp"
});

Mask 是指导，不是像素级锁定

Mask 需要透明通道，并与第一张输入图尺寸一致；透明区域表示希望编辑的区域。官方同时提醒，GPT Image 把 Mask 当作提示指导，可能不会严格遵守边界。提示词要明确写出“保留什么、改变什么、禁止新增什么”，并评测边缘、文字、手部、Logo 和品牌颜色。

尺寸、质量、格式和透明背景

自定义宽高必须是 16 的倍数，宽高比在 1:3 到 3:1 之间，单边不超过 3840 像素，总像素在 655,360 到 8,294,400 之间；超过 2560×1440 的尺寸仍属于实验性范围。不要把这些约束硬编码成永远不变的产品承诺，部署前读取当前模型文档。

流式生成：partial_images 不是免费预览

Image API 与 Responses API 都支持流式图片生成。partial_images 可设为 0–3：0 只返回最终图，正数会尽量返回对应数量的局部图，但如果最终图生成得更快，实际收到的局部图可能更少。官方当前说明每张局部图额外计入 100 个图像输出 Token。

const stream = await openai.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "现代城市夜景插画，宽幅，无文字",
  stream: true,
  partial_images: 2,
  size: "1536x1024"
});

for await (const event of stream) {
  if (event.type === "image_generation.partial_image") {
    // 标记为预览，不要覆盖最终资产
    savePreview(event.partial_image_index, event.b64_json);
  }
}

界面应把局部图标为“生成中”，最终事件到达后再写入正式资产。断流时不要把最后一张局部图当成最终结果；用内部作业 ID、提示词版本和请求状态做幂等，避免用户重试导致重复生成和重复计费。

成本：按输入、输出和工作流一起算

截至 2026-10-31，Sunburst 与 Flare 的标准价格相同：每百万图像输入 Token 8 美元、缓存图像输入 2 美元、图像输出 30 美元、文本输入 5 美元、缓存文本输入 1.25 美元。Responses API 还会产生顶层主模型用量；直接 Images API 的编辑请求不享受 Responses image_generation 工具的缓存输入定价。价格会调整，页面和报价系统应以当前官方 Pricing 与生成计算器为准。

• 单位成功成本：总生成费用 ÷ 通过质量门槛的图片数，而不是只看单次调用价格。
• 参考图成本：记录输入图数量、分辨率和是否重复使用；多图编辑的输入 Token 会增加。
• 局部图成本：partial_images 提升体验，但每张局部图额外计费。
• 存储与分发：Base64 解码后还要承担对象存储、CDN、缩略图与清理费用。

项目维度查看消费可参考 OpenAI API Usage 指南；API Key 与最小权限见 API Key 安全指南。

安全、隐私与生产边界

• API Key 只放后端，按 Project/Service Account 限权；浏览器上传先进入受控后端或签名存储。
• 验证 MIME、真实文件格式、尺寸、大小和图像数量；对解码、转码和外部 URL 设置超时与资源限制。
• 对参考图、人物照片、品牌资产和自定义素材取得适用授权，定义原图、生成图、Mask 和日志的保留/删除周期。
• 使用稳定且不含个人信息的 safety_identifier，监控异常请求、重复失败和高频批量生成。
• 生成前后根据产品风险接入内容审核；Moderation 能力和业务策略见 OpenAI Moderation API 指南。
• Vision 结果可能出错，不能用图片理解结果直接做不可逆高风险决定；需要精确 OCR、坐标或计数时保留专门工具和人工复核。

评测：从“好不好看”变成可复现标准

每次模型、提示模板、尺寸或质量变更都用同一版本化样本回归。保存提示词版本、模型快照、参数、输入资产哈希和人工评分，但不要把敏感原图或个人信息写入普通日志。

上线前检查清单

1. 已经区分 Image API、Responses image_generation 与 Vision 图片理解，没有混用端点和计费。
2. 新集成使用 Sunburst 或 Flare；旧 DALL·E、GPT Image 1 和 Variations 依赖已移除或有迁移计划。
3. API Key 只在后端；safety_identifier 稳定、保护隐私且不超过 128 字符。
4. 参考图数量、格式、单图大小、Mask 透明通道和尺寸已在上传阶段验证。
5. 尺寸、质量、格式、透明背景、压缩与流式局部图都有真实设备和素材测试。
6. 局部图不会被保存为最终资产，失败重试有幂等与重复计费保护。
7. 成本包含文本/图像输入、输出、局部图、顶层 Responses 模型、存储与 CDN。
8. 提示遵循、文字、主体保持、延迟、失败率、安全和单位成功成本都有基线。

常见问题

本文核对日期为 2026-10-31。模型名称、端点参数、限制、价格和验证要求可能调整，生产上线前请重新读取官方 Image generation、Images API Reference 与 Pricing。