OpenAI Responses API 怎样为图片生成请求绑定输入图

如果应用要让模型参考一张商品图、草图或上一轮生成结果，关键不是把图片地址拼到提示词里，而是把它作为 Responses API 的 input_image 内容项传入。请求通常由一段 input_text 说明任务，再配一项或多项 input_image 组成；图片可以使用完整 URL、Base64 data URL 或 Files API 返回的 file_id。

官方参考：https://developers.openai.com/api/docs/guides/image-generation

最稳定的判断方式是：先把文字和图片放进同一个 user content 数组，再根据图片来源选择 URL、data URL 或 file_id；如果是修改已有图片，可显式设置 action: "edit"，返回时从 image_generation_call 读取图像结果。

• 公开图片：使用完整的 https:// 图片地址。
• 本地或内存图片：转为 data:image/...;base64,...。
• 已通过 Files API 上传的图片：使用文件 ID，不要把 ID 填到 image_url。

先把 Responses API 的输入层次摆对

这类请求最容易出错的地方是层次。input 可以是文本，也可以是消息数组；当需要同时传文字和图片时，应使用消息数组，并在 content 中放入一个 input_text 和至少一个 input_image。图片不是普通字符串，也不是工具配置里的提示词字段。

下面的结构图只表达请求对象、消息内容和图片工具之间的静态关系，不代表一次真实运行截图。

三种方式怎样绑定输入图

官方资料给出的输入图入口可以归为三类。公开且可访问的图片适合使用 URL；程序已经拿到图片字节时适合使用 Base64 data URL；图片先通过 Files API 上传并获得文件 ID 后，使用 file_id 更适合复用和多轮处理。

from openai import OpenAI
import base64

client = OpenAI()

# 方式一：图片已经放在可访问的 HTTPS 地址
remote_image = {
    "type": "input_image",
    "image_url": "https://example.com/reference.png",
    "detail": "auto",
}

# 方式二：程序已有图片字节，拼成完整的 data URL
with open("reference.png", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("ascii")
local_image = {
    "type": "input_image",
    "image_url": f"data:image/png;base64,{encoded}",
    "detail": "auto",
}

# 方式三：已通过 Files API 得到的文件 ID
file_image = {
    "type": "input_image",
    "file_id": "file_abc123",
    "detail": "auto",
}

response = client.responses.create(
    model="gpt-6-astra",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "参考输入图，生成一张风格统一的产品场景图。"},
            # 三选一；生产代码不要同时传入同一张图的三种表示
            file_image,
        ],
    }],
    tools=[{
        "type": "image_generation",
        "model": "gpt-image-2.5-sunburst",
        "action": "edit",
    }],
)

示例中的 file_abc123 只是字段形状示意，不能当作真实文件 ID。实际项目要把 remote_image、local_image 或 file_image 中的一种放入 content。如果来源是 JPEG 或 WebP，data URL 的 MIME 类型也要与真实文件匹配。

生成与编辑：什么时候设置 action

已有输入图时，任务通常是“参考后生成”或“在原图上修改”。把 action 设为 edit 可以明确告诉工具围绕已有图片处理；设为 generate 则表示始终创建新图；不填写时使用 auto，由支持的主模型根据上下文选择。这个字段控制的是图片工具的意图，不会替代 input_image。

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

const openai = new OpenAI();
const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{
    role: "user",
    content: [
      { type: "input_text", text: "保留主体轮廓，把背景改成柔和的浅色工作室环境。" },
      { type: "input_image", file_id: "file_abc123", detail: "auto" },
    ],
  }],
  tools: [{
    type: "image_generation",
    model: "gpt-image-2.5-sunburst",
    // 已有输入图并要求修改时，显式表达编辑意图
    action: "edit",
  }],
});

const imageCall = response.output.find(
  (item) => item.type === "image_generation_call",
);

if (!imageCall?.result) {
  // 没有图像调用或结果为空时，不要写出一个假文件
  throw new Error("响应中没有可保存的图像结果");
}

// result 是 Base64 图像数据，按实际输出格式保存到文件
fs.writeFileSync("edited.png", Buffer.from(imageCall.result, "base64"));

输出处理要围绕 response.output 中的 image_generation_call。不要把 response.output_text 当作图片，也不要假设每次响应都一定包含图像调用；没有结果时应记录原始响应状态并走错误处理。

常见绑定错误与排查顺序

排查时按“输入对象类型 → content 层次 → 图片表示方式 → action → 输出对象”顺序看，通常比反复改提示词更快。输入图只负责提供视觉上下文，不能替应用替换掉必要的任务描述、权限配置或结果处理。

落地前的最小清单

1. 确认请求使用的是 Responses API，并把文字和图片放在同一个 user content 数组。
2. 根据图片来源选择 URL、data URL 或 file_id；不要混用字段。
3. 已有图片要修改时，优先显式写 action: "edit"，同时说明保留区域和修改目标。
4. 从 image_generation_call.result 读取 Base64 结果，空结果进入错误处理。

常见问题

可以一次传多张输入图吗？

可以。把多项 input_image 放进同一个 content 数组，并在文字中说明每张图的角色，避免模型无法区分参考对象。

为什么有 file_id 还要保留 input_text？

file_id 只标识输入图，不能完整表达你想生成、修改或保留什么。文字指令仍应放在 input_text 中。

输入图传进去后一定会返回图片吗？

不应这样假设。应用仍需检查返回输出是否包含 image_generation_call 及其 result，并把缺失结果当作一次需要处理的响应异常。