> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipellm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 编辑图像

> 用 GPT 图像模型编辑已有图像，可选遮罩。

编辑接口接收一张或多张源图，加上描述改动的提示词。带遮罩时只重绘透明区域；不带遮罩时，模型会参照源图重绘整幅画面。

两种请求编码都可以，PipeLLM 均原样透传：

* `multipart/form-data`，直接上传图像字节。OpenAI SDK 发的就是这种。
* `application/json`，用 `images` 数组传 `file_id` 或 `image_url`，最多 16 张参考图。

<ParamField body="image" type="file | array" required>
  源图，可以多张。multipart 下用 `image[]` 传文件部分，JSON 下用 `images` 数组。支持 PNG、JPEG、WebP。
</ParamField>

<ParamField body="prompt" type="string" required>
  编辑后的图像应该呈现什么。GPT 图像模型上限 32,000 字符。
</ParamField>

<ParamField body="model" type="string">
  图像模型 ID，例如 `gpt-image-2.5-sunburst`。
</ParamField>

<ParamField body="mask" type="file">
  一张 PNG，其中透明像素标记需要重绘的区域，尺寸必须和源图一致。不传则由模型编辑整幅图像。
</ParamField>

<ParamField body="n" type="integer" default="1">
  返回数量，1–10。
</ParamField>

<ParamField body="size" type="string" default="auto">
  `auto`、`1024x1024`、`1536x1024`、`1024x1536`，或能被 16 整除的自定义 `宽x高`。
</ParamField>

<ParamField body="quality" type="string" default="auto">
  `low`、`medium`、`high` 或 `auto`。`gpt-image-2.5` 系列额外支持 `xhigh` 和 `max`。
</ParamField>

<ParamField body="input_fidelity" type="string" default="low">
  `high` 会更严格地保留源图里的人脸、logo 和细节纹理，代价是输入 token 更多；`low` 给模型更大的发挥空间。
</ParamField>

<ParamField body="background" type="string" default="auto">
  `transparent`、`opaque` 或 `auto`。透明背景要求输出为 `png` 或 `webp`。
</ParamField>

<ParamField body="output_format" type="string" default="png">
  `png`、`jpeg` 或 `webp`。
</ParamField>

<ParamField body="output_compression" type="integer" default="100">
  压缩级别 0–100，仅对 `jpeg` 和 `webp` 生效。
</ParamField>

<ParamField body="user" type="string">
  稳定的终端用户标识。
</ParamField>

<RequestExample>
  ```bash cURL theme={"dark"}
  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"
  ```

  ```python Python theme={"dark"}
  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))
  ```

  ```typescript TypeScript theme={"dark"}
  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"));
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"dark"}
  {
    "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
    }
  }
  ```
</ResponseExample>

响应结构与 [生成图像](/zh/api-reference/image/generations) 一致：图像字节以 base64 放在 `data[].b64_json`，`usage.input_tokens_details.image_tokens` 对应你上传的源图。

## 组合多张参考图

传多张源图时，模型会跨图合成——比如商品加场景、人物加服装。顺序有意义：提示词里描述参考图的顺序要和你传入的顺序一致，例如「把第一张参考图里的人物换上第二张参考图里的服装」。

遮罩只作用于第一张图。

## 长时间请求

编辑接口的保活行为和生成一致：上游静默 90 秒后，网关每 30 秒在 JSON 响应体之前写入一个空白填充块。见 [长时间请求](/zh/api-reference/image/generations#长时间请求)。

## 错误

错误信封与 [错误处理](/zh/api-reference/errors) 一致。

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    遮罩尺寸与源图不一致、上传文件无法解析，或 `size` 取值模型不接受。

    ```json theme={"dark"}
    {
      "error": {
        "type": "invalid_request_error",
        "code": "400",
        "message": "The mask must have the same dimensions as the image"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 authentication_error">
    ```json theme={"dark"}
    {
      "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."
      }
    }
    ```
  </Accordion>

  <Accordion title="413 invalid_request_error">
    上传体积超出限制。请先把源图缩小再发送。
  </Accordion>

  <Accordion title="429 rate_limit_error">
    见 [速率限制](/zh/api-reference/rate-limits)。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.