GPT图像2.5 API指南：使用Sunburst和Flare生成与编辑图像

使用 Image API 进行直接的单步生成和编辑。当图像创建属于对话或多步流程时，使用 Responses API。在 Image API 中，直接选择 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

先选择界面

图像API提供了生成和编辑端点。响应API支持作为工具的迭代图像生成，并能将图像输入和输出保持在上下文中。这一架构决策比SDK语法更为重要。

最小生成模式

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "一个干净的设计插画，描绘一座太阳能图书馆，无文字元素"
  size: "1536x1024",
  quality: "中等",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

将API密钥保存在服务器端，并远离源代码控制。

输出控制

两个模型均支持从自动到最高质量、官方限制内的自定义尺寸、PNG/JPEG/WebP格式、JPEG/WebP压缩，以及透明或不透明背景。如需Alpha通道，请使用PNG或WebP格式。

编辑模式

使用一张或多张图片调用编辑端点，并提供一个将更改与保留细节分开的提示。在发送前验证输入类型和大小。为每个参考赋予一个角色。

生产验证

存储请求ID、模型或快照、提示版本、大小、质量、输出格式、参考信息、延迟和接受结果。仅重试瞬时故障；在不更改请求的情况下，不要自动重试语义错误的输出。

模型路由

将日常任务路由到Flare，将高精度任务路由到Sunburst。使用固定基准，避免假设更快的模型更便宜，因为当前令牌费率匹配。

错误处理

处理身份验证、组织验证、速率限制、无效尺寸、内容审核和空输出。对符合条件的瞬时错误使用带抖动的指数退避策略，并限制重试次数。切勿不必要地记录私人图像数据。

下游动画

解码并批准图像后，存储来源信息并将资产传递给下游工作流。当静态图像需要变成以角色为主导的故事板、视频或编辑动画时，Elser AI 是相关的。请在实时产品中验证支持的上传和模型选项。

生成端点与编辑端点

使用文本生成新图像时使用生成功能。当一张或多张现有图像定义了主体或初始状态时，使用编辑功能。对于多参考编辑，请按稳定顺序发送输入，并在提示中标识该顺序。在请求前验证文件类型和尺寸，以便错误输入在本地失败。

用于迭代工作的响应API

当用户创建图像、以对话方式评估图像并请求后续更改时，Responses API 非常有用。图像生成工具可以参与更大的响应流程，并且图像文件 ID 可以保留在上下文中。这减少了应用端的拼接工作，但产品仍然需要明确的状态和版本控制。“和之前一样”不足以作为关键约束条件；请重新表述。

更安全的应用程序架构

保持客户端、任务队列、资产存储和元数据存储相互独立。客户端提交一个简要说明。服务器验证该说明并创建一个任务。工作进程调用OpenAI，解码结果并将其存储在生成的资产ID下。元数据记录模型快照、提示词、设置、引用和审核结果。客户端收到一个短期有效的资产URL，而非原始凭证。

长时间运行的调用不应占用脆弱的浏览器请求。复杂提示可能需要大量时间，因此应展示待处理、已完成和失败的状态。使任务提交具有幂等性，以避免客户端重试时产生重复费用。

验证规则

检查自定义尺寸是否满足文档规定的16的倍数、边缘、比例及总像素限制。背景透明时要求使用PNG或WebP格式。将压缩值限制在支持范围内。仅允许已知的质量和模型参数。在API调用前拒绝缺少提示词的情况。

可靠性与可观测性

记录请求ID、HTTP状态、错误类别、尝试次数和延迟，不记录私有镜像或机密信息。使用带抖动的指数退避重试速率限制和符合条件的服务器错误。不要原样重试身份验证、无效参数或策略错误。对尝试次数设置上限，并返回有用的产品消息。

显示器：

成功率和接受图像率。
按模型和质量划分的p50和p95延迟。
输入和输出令牌。
重试和重复任务。
审核结果。
存储和交付失败。

安全与权利

将API密钥存储在服务端密钥管理器中。对源图像和生成的图像实施访问控制。设置保留规则，移除不应暴露的元数据，并记录用户对上传材料的权利。OpenAI指出，访问GPT图像模型可能需要进行组织验证；请将其作为入职前提条件处理，而非运行时意外。

快照策略

使用未注明日期的ID以获取持续模型更新。当可重复性更为重要时，固定一个带日期的快照。在更改生产流量前，使用相同的基准评估新快照。存储每个资产返回或配置的实际模型标识符。

如果启动文章中包含代码，请在其旁边显示带有日期的验证日期。读者应理解，模型的可用性、SDK 语法、速率限制和组织要求可能会独立于文章的概念架构发生变化。

类型化请求契约

即使图像模型本身不提供结构化输出，也要定义一个内部模式。一项任务可能包含prompt（提示词）、workflow（工作流）、model（模型）、quality（质量）、width（宽度）、height（高度）、format（格式）、background（背景）、compression（压缩）、参考资源ID以及一个幂等键。在转换为SDK调用之前对其进行验证。

不要从浏览器暴露任意的模型名称或文件路径。应将客户端可见的少量选项映射到服务器认可的值。通过受访问控制的资产ID解析引用，并验证当前用户是否有权读取这些资产。

编辑请求草图

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [fs.createReadStream("approved-character.png")],
  prompt: `只将外套改为深绿色羊毛。
保留面部、头发、眼睛颜色、姿势、手部、构图和背景。
不要添加文字、珠宝或其他人。`
  size: "1024x1536",
  quality: "高",
  output_format: "png"
});

const bytes = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("character-green-coat.png", bytes);

确切的SDK接口可能会演变，因此在部署前请对照当前官方指南验证示例。生产代码应负责任地流式处理或缓冲，验证响应是否存在，并原子化存储，而不是假设每次调用都返回可用数据。

幂等性与重复成本

用户双击或网络重试可能导致同一昂贵的生成任务被提交两次。在创建任务时分配一个幂等键，在分发前持久化任务，当相同键再次出现时返回已有任务。工作进程应仅获取一次任务并记录最终状态。

如果你有意生成多个变体，请将其表示为一个明确的产品操作，而非意外的重试。图像API在文档中支持通过n参数生成多张图像，但你的成本和审核模型应统计每一次输出。

审核与失败用户体验

所有提示词和图像均需经过安全过滤。避免透露敏感的内部审核细节，但应给予用户足够的指导以修改合法请求。将政策拒绝与无效设置、授权、速率限制及临时服务故障区分开来。

当Sunburst不可用时，切勿静默替换为其他模型，这可能违反质量或合同约定。应返回明确的状态，或仅在产品已披露并记录该行为的情况下使用备用方案。

资产存储与交付

在内存中解码base64并设置大小限制，验证声明的格式，生成校验和并存储不可变的原始文件。单独生成缩略图。通过短期有效的签名URL和适当的内容类型提供服务。保留透明PNG/WebP的Alpha通道，避免有损转换破坏可交付成果。

以适当的访问控制存储提示和参考资料，以匹配其敏感程度。定义保留和删除行为。没有来源的生成文件难以审计、复现或安全地交给Elser动画项目。

发布前检查清单

账户和组织访问权限已确认。
API 密钥是服务器端且可轮换的。
模型ID和维度规则已列入白名单。
作业提交是幂等的。
重试次数有限且分类。
使用情况、延迟和接受度受到监控。
图像和元数据具有保留规则。
对于身份、品牌和文本敏感的输出，存在人工审核。
已记录一份带日期的快照策略和回滚路径。

常见问题解答

我应该选择哪个 API？

Image API用于直接生成/编辑；Responses API用于对话式或多步骤图像体验。

我可以请求多张图片吗？

Image API 在文档中支持用于多个输出的 n 参数。

API 是否返回一个 URL？

当前指南展示了图像API的base64编码图像数据；请解码并安全存储。

结论

可靠的集成将清晰的模型路由与严格的验证、可观测性和资产审查相结合。先构建最小的直接请求，仅在核心图像路径可靠时，再添加对话状态或下游动画。