curl https://api.pipellm.ai/v1/images/edits \
-H "Authorization: Bearer $PIPELLM_API_KEY" \
-F model="gpt-image-2.5-sunburst" \
-F image="@room.png" \
-F mask="@room-mask.png" \
-F prompt="Replace the sofa with a green velvet one" \
-F size="1024x1024"
import base64
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["PIPELLM_API_KEY"],
base_url="https://api.pipellm.ai/v1",
)
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("room.png", "rb"),
mask=open("room-mask.png", "rb"),
prompt="Replace the sofa with a green velvet one",
size="1024x1024",
)
with open("room-edited.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({
apiKey: process.env.PIPELLM_API_KEY,
baseURL: "https://api.pipellm.ai/v1",
});
const result = await client.images.edit({
model: "gpt-image-2.5-sunburst",
image: await toFile(fs.createReadStream("room.png"), "room.png"),
mask: await toFile(fs.createReadStream("room-mask.png"), "room-mask.png"),
prompt: "Replace the sofa with a green velvet one",
size: "1024x1024",
});
fs.writeFileSync("room-edited.png", Buffer.from(result.data[0].b64_json, "base64"));
{
"created": 1726400000,
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"background": "opaque",
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
],
"usage": {
"input_tokens": 342,
"input_tokens_details": { "text_tokens": 14, "image_tokens": 328 },
"output_tokens": 1056
}
}
编辑图像
用 GPT 图像模型编辑已有图像,可选遮罩。
POST
/
v1
/
images
/
edits
curl https://api.pipellm.ai/v1/images/edits \
-H "Authorization: Bearer $PIPELLM_API_KEY" \
-F model="gpt-image-2.5-sunburst" \
-F image="@room.png" \
-F mask="@room-mask.png" \
-F prompt="Replace the sofa with a green velvet one" \
-F size="1024x1024"
import base64
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["PIPELLM_API_KEY"],
base_url="https://api.pipellm.ai/v1",
)
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("room.png", "rb"),
mask=open("room-mask.png", "rb"),
prompt="Replace the sofa with a green velvet one",
size="1024x1024",
)
with open("room-edited.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({
apiKey: process.env.PIPELLM_API_KEY,
baseURL: "https://api.pipellm.ai/v1",
});
const result = await client.images.edit({
model: "gpt-image-2.5-sunburst",
image: await toFile(fs.createReadStream("room.png"), "room.png"),
mask: await toFile(fs.createReadStream("room-mask.png"), "room-mask.png"),
prompt: "Replace the sofa with a green velvet one",
size: "1024x1024",
});
fs.writeFileSync("room-edited.png", Buffer.from(result.data[0].b64_json, "base64"));
{
"created": 1726400000,
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"background": "opaque",
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
],
"usage": {
"input_tokens": 342,
"input_tokens_details": { "text_tokens": 14, "image_tokens": 328 },
"output_tokens": 1056
}
}
编辑接口接收一张或多张源图,加上描述改动的提示词。带遮罩时只重绘透明区域;不带遮罩时,模型会参照源图重绘整幅画面。
两种请求编码都可以,PipeLLM 均原样透传:
响应结构与 生成图像 一致:图像字节以 base64 放在
multipart/form-data,直接上传图像字节。OpenAI SDK 发的就是这种。application/json,用images数组传file_id或image_url,最多 16 张参考图。
file | array
必填
源图,可以多张。multipart 下用
image[] 传文件部分,JSON 下用 images 数组。支持 PNG、JPEG、WebP。string
必填
编辑后的图像应该呈现什么。GPT 图像模型上限 32,000 字符。
string
图像模型 ID,例如
gpt-image-2.5-sunburst。file
一张 PNG,其中透明像素标记需要重绘的区域,尺寸必须和源图一致。不传则由模型编辑整幅图像。
integer
默认值:"1"
返回数量,1–10。
string
默认值:"auto"
auto、1024x1024、1536x1024、1024x1536,或能被 16 整除的自定义 宽x高。string
默认值:"auto"
low、medium、high 或 auto。gpt-image-2.5 系列额外支持 xhigh 和 max。string
默认值:"low"
high 会更严格地保留源图里的人脸、logo 和细节纹理,代价是输入 token 更多;low 给模型更大的发挥空间。string
默认值:"auto"
transparent、opaque 或 auto。透明背景要求输出为 png 或 webp。string
默认值:"png"
png、jpeg 或 webp。integer
默认值:"100"
压缩级别 0–100,仅对
jpeg 和 webp 生效。string
稳定的终端用户标识。
curl https://api.pipellm.ai/v1/images/edits \
-H "Authorization: Bearer $PIPELLM_API_KEY" \
-F model="gpt-image-2.5-sunburst" \
-F image="@room.png" \
-F mask="@room-mask.png" \
-F prompt="Replace the sofa with a green velvet one" \
-F size="1024x1024"
import base64
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["PIPELLM_API_KEY"],
base_url="https://api.pipellm.ai/v1",
)
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("room.png", "rb"),
mask=open("room-mask.png", "rb"),
prompt="Replace the sofa with a green velvet one",
size="1024x1024",
)
with open("room-edited.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({
apiKey: process.env.PIPELLM_API_KEY,
baseURL: "https://api.pipellm.ai/v1",
});
const result = await client.images.edit({
model: "gpt-image-2.5-sunburst",
image: await toFile(fs.createReadStream("room.png"), "room.png"),
mask: await toFile(fs.createReadStream("room-mask.png"), "room-mask.png"),
prompt: "Replace the sofa with a green velvet one",
size: "1024x1024",
});
fs.writeFileSync("room-edited.png", Buffer.from(result.data[0].b64_json, "base64"));
{
"created": 1726400000,
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"background": "opaque",
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
],
"usage": {
"input_tokens": 342,
"input_tokens_details": { "text_tokens": 14, "image_tokens": 328 },
"output_tokens": 1056
}
}
data[].b64_json,usage.input_tokens_details.image_tokens 对应你上传的源图。
组合多张参考图
传多张源图时,模型会跨图合成——比如商品加场景、人物加服装。顺序有意义:提示词里描述参考图的顺序要和你传入的顺序一致,例如「把第一张参考图里的人物换上第二张参考图里的服装」。 遮罩只作用于第一张图。长时间请求
编辑接口的保活行为和生成一致:上游静默 90 秒后,网关每 30 秒在 JSON 响应体之前写入一个空白填充块。见 长时间请求。错误
错误信封与 错误处理 一致。400 invalid_request_error
400 invalid_request_error
遮罩尺寸与源图不一致、上传文件无法解析,或
size 取值模型不接受。{
"error": {
"type": "invalid_request_error",
"code": "400",
"message": "The mask must have the same dimensions as the image"
}
}
401 authentication_error
401 authentication_error
{
"error": {
"type": "authentication_error",
"code": "401",
"message": "Incorrect API key provided. Please visit https://console.pipellm.ai/account/api-keys to find your API key."
}
}
413 invalid_request_error
413 invalid_request_error
上传体积超出限制。请先把源图缩小再发送。
429 rate_limit_error
429 rate_limit_error
见 速率限制。
此页面对您有帮助吗?