改图与多图

上传一张或多张图片，按文字要求修改或融合。

POST/v1/images/edits通用参数说明

开始前

需要准备	说明
API Key	在 OfoxAI 控制台创建，替换代码里的 `YOUR_OFOX_API_KEY`
运行环境	cURL 需要装 `jq` 来解码图片；Python 需要 `pip install openai`；Node.js 18 及以上，不用装依赖
图片	当前目录放一张 `input.png`；多图融合再放一张 `input2.png`。格式 PNG 或 JPEG，单张 ≤ 15 MB
超时	客户端超时设为 600 秒。高画质、大尺寸或改图可能要等好几分钟

代码里要用到的

API 地址https://api.ofox.io/v1

模型 IDopenai/gpt-image-2.5-sunburst示例代码里用的是 flare，改图推荐换成 sunburst

API Key把代码里的 YOUR_OFOX_API_KEY 换成你的 Key

Python 依赖pip install openai

改一张图

以下代码都原样运行通过，结果保存为当前目录下的 output.png。

cURL

Terminal


curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "prompt=把背景换成木纹桌面,主体保持不变" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",  # 替换成你的 Key
    base_url="https://api.ofox.io/v1",
)
 
result = client.images.edit(
    model="openai/gpt-image-2.5-flare",
    image=open("input.png", "rb"),
    prompt="把背景换成木纹桌面,主体保持不变",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print("已保存 output.png")

Node.js

edit.mjs


// Node.js 18+,无需安装任何依赖
import { readFileSync, writeFileSync } from "node:fs";
 
const form = new FormData();
form.append("model", "openai/gpt-image-2.5-flare");
form.append("image", new Blob([readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("prompt", "把背景换成木纹桌面,主体保持不变");
form.append("quality", "low");
 
const res = await fetch("https://api.ofox.io/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OFOX_API_KEY", // 替换成你的 Key
  },
  body: form,
});
 
const json = await res.json();
if (!res.ok) throw new Error(JSON.stringify(json));
writeFileSync("output.png", Buffer.from(json.data[0].b64_json, "base64"));
console.log("已保存 output.png");

不传 size 时，输出尺寸由模型决定，不一定和原图一样大。要保持原尺寸，请显式传入，例如 size=1024x1024。

prompt 怎么写

写清楚两件事：要改什么，以及什么保持不变。

场景	写法示例
改一张图	把背景换成木纹桌面，主体保持不变
多图融合	把第一张图的主体放到第二张图的背景上

多图时按上传顺序称呼「第一张图」「第二张图」。只想改图中的一小块，用局部重绘更稳。

多图融合

一次传多张参考图。图片的上传顺序，对应 prompt 里的「第一张」「第二张」。需要在当前目录放好 input.png 和 input2.png。

cURL

Terminal


# 一次最多 16 张,每张 ≤ 15 MB
curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image[]=@input.png" \
  -F "image[]=@input2.png" \
  -F "prompt=把第一张图的主体放到第二张图的背景上" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

供应商

不需要指定供应商。三款模型的改图接口 Azure 和 OpenAI 都提供，网关会自动路由。

有内容审核方面的需求时可以指定供应商，但改图接口只能用请求头 X-OfoxAI-Provider-Type，写在表单里的 extra_body 会被忽略。指定后若该供应商不可用，请求不会自动切换到其他供应商。详见指定供应商。

参数取值

改图接口特有的参数如下。model、n、output_format 等和文生图相同，见文生图 · 参数取值。

必填

image必填fileform

要修改的图片。多张图时，字段名写成 image[] 并重复传入；Python SDK 里直接传列表。

▸ 详情

参考图也按 token 计费：一张 1024×1024 的参考图实测计 1,024 个输入 token，所以改图比同尺寸的文生图贵。

▶高级 · 1X-OfoxAI-Provider-Type展开

X-OfoxAI-Provider-Typestringheader· 可选azure_foundryopenai

一般不用传，网关会自动路由。只在想固定某一家供应商时使用。

上传限制

项目	限制
单张参考图	≤ 15 MB
整个请求	≤ 50 MB
张数	网关不限制，建议不超过 16 张
格式	PNG、JPEG

模型会把参考图缩放到 1024px 左右处理。单张超过 5 MB 只会让上传变慢，不会让效果更好。

常见报错

报错	原因	怎么处理
`Invalid image file or mode`	上传的图片不是标准 PNG 或 JPEG	重新导出为 PNG 或 JPEG
`Invalid file 'image[0]': unsupported mimetype`	上传的文件不是图片	上传 PNG、JPEG 或 WebP 图片
`does not support the 'input_fidelity' parameter`	传了 `input_fidelity`	删除该参数，本系列始终以高保真处理参考图
`moderation_blocked`	提示词或参考图被上游安全系统拦截	修改提示词或更换参考图后再试
`provider_type_unavailable`	手动指定的供应商不提供这个模型	去掉 `X-OfoxAI-Provider-Type` 请求头
`Invalid size`	传的尺寸不满足四条约束	见尺寸
`404 model_not_found`	模型 ID 拼错或大小写不对	从本页复制模型 ID

其他报错见完整报错表。

官方文档

OpenAI 官方文档写的是直连 OpenAI 时的行为。在 OfoxAI 上调用，以本系列文档的实测结论为准，例如改图不需要指定供应商。