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

# 图像编辑

> 使用 Venice 同步的图像编辑、多重编辑和背景移除 API，对图像进行编辑、inpaint、分层输入合成以及背景移除。

Venice 上的图像编辑是同步的。将源图像发送到 `/image/edit` 或 `/image/multi-edit`，编辑后的结果会在同一响应中以 PNG 文件形式返回。对于抠图，`/image/background-remove` 返回透明 PNG。

<Warning>
  图像编辑端点是实验性的，模型特有行为可能会随时间变化。
</Warning>

## 端点

| 端点                              | 用途              | 最适合                         |
| ------------------------------- | --------------- | --------------------------- |
| `POST /image/edit`              | 用 prompt 编辑单张图像 | 通用编辑和基于 prompt 的 inpainting |
| `POST /image/multi-edit`        | 使用 1-3 张分层图像编辑  | 借助遮罩或叠加层实现更可控的编辑            |
| `POST /image/background-remove` | 移除图像背景          | 产品、人像和素材的透明抠图               |

## 何时使用哪个端点

* 当您有一张源图像并希望用 prompt 改变、移除或重新风格化其部分时，使用 `/image/edit`。
* 当您需要从遮罩、叠加或参考层获得额外控制时，使用 `/image/multi-edit`。
* 当您只想要一个干净的、透明背景的前景主体时，使用 `/image/background-remove`。

<Note>
  对于 inpainting，请使用 `/image/edit` 或 `/image/multi-edit`。`/image/generate` 上旧的 `inpaint` 参数已弃用。
</Note>

## 第 1 步：编辑单张图像

单图像编辑是最简单的 inpainting 流程。发送一张图像加一个简短 prompt，例如 "remove the sign"、"change the sky to sunrise" 或 "replace the background with a studio backdrop"。

**请求：**

```bash theme={"system"}
POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-edit",
  "prompt": "Replace the cloudy sky with a warm sunrise while preserving the buildings and canal",
  "image": "https://example.com/venice-canal.jpg"
}
```

**响应（200）：**
响应体是原始的 `image/png` 二进制数据。直接保存为文件即可。

<CodeGroup>
  ```python Python theme={"system"}
  import base64
  import os
  import requests

  with open("input.jpg", "rb") as f:
      image_base64 = base64.b64encode(f.read()).decode("utf-8")

  response = requests.post(
      "https://api.venice.ai/api/v1/image/edit",
      headers={
          "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "qwen-edit",
          "prompt": "Remove the tourist crowd from the square and keep the architecture intact",
          "image": image_base64,
      },
  )

  with open("edited.png", "wb") as f:
      f.write(response.content)
  ```

  ```javascript Node.js theme={"system"}
  import fs from "fs";

  const imageBase64 = fs.readFileSync("input.jpg").toString("base64");

  const response = await fetch("https://api.venice.ai/api/v1/image/edit", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "qwen-edit",
      prompt: "Remove the tourist crowd from the square and keep the architecture intact",
      image: imageBase64,
    }),
  });

  const editedImage = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("edited.png", editedImage);
  ```

  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/image/edit \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -o edited.png \
    -d '{
      "model": "qwen-edit",
      "prompt": "Colorize this black and white portrait naturally",
      "image": "https://example.com/portrait-bw.jpg"
    }'
  ```
</CodeGroup>

## 第 2 步：使用 multi-edit 进行遮罩或分层 inpainting

`/image/multi-edit` 接受最多三张图像。第一张是基础图像。其余被视为编辑层或遮罩，比仅 prompt 编辑提供更多控制。

当您想要以下场景时，这是更好的选择：

* 用遮罩定位特定区域
* 将现有构图与叠加层组合
* 比单图像 prompt 更严格地约束编辑

**JSON 请求：**

```json theme={"system"}
{
  "modelId": "qwen-edit",
  "prompt": "Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective",
  "images": [
    "https://example.com/street-scene.png",
    "https://example.com/billboard-mask.png"
  ]
}
```

**Multipart 请求：**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=qwen-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "images=@street-scene.png" \
  -F "images=@billboard-mask.png" \
  -o multi-edited.png
```

与 `/image/edit` 一样，响应体是原始的 `image/png` 数据。

<Note>
  `/image/multi-edit` 目前在请求 schema 中使用 `modelId` 字段，而非 `model`。
</Note>

***

## Inpainting 技巧

基于 prompt 的 inpainting 在指令简短且局部时效果最好：

* `remove the tree`
* `change the sky to sunset`
* `replace the logo with a blank sign`
* `restore the torn corner of the photo`

对于更大范围的场景改动，请描述应保持不变的部分：

```text theme={"system"}
Replace the background with a modern photo studio backdrop while preserving the subject pose, facial features, and clothing.
```

如果编辑总是影响错误的区域，请从 `/image/edit` 切换到 `/image/multi-edit` 并提供遮罩或叠加层。

***

## 第 3 步：移除背景

当您希望前景主体在透明背景上单独显示时，请使用 `/image/background-remove`。此端点返回带 alpha 透明度的 PNG。

**使用图像 URL：**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o cutout.png \
  -d '{
    "image_url": "https://example.com/product-photo.jpg"
  }'
```

**使用本地文件上传：**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "image=@product-photo.jpg" \
  -o cutout.png
```

背景移除适用于：

* 电商产品照片
* 个人资料照片和人像
* 您打算放在新背景上的素材

***

## 请求参数

### `/image/edit`

| 参数             | 类型                 | 必填  | 默认          | 说明             |
| -------------- | ------------------ | --- | ----------- | -------------- |
| `image`        | 文件、base64 字符串或 URL | 是   | -           | 要编辑的源图像        |
| `prompt`       | string             | 是   | -           | 编辑的文本指令        |
| `model`        | string             | 否   | `qwen-edit` | 编辑模型 ID        |
| `aspect_ratio` | string             | 否   | 模型默认        | 支持的模型的输出比例     |
| `modelId`      | string             | 已弃用 | -           | `model` 的已弃用别名 |

### `/image/multi-edit`

| 参数        | 类型                          | 必填 | 默认          | 说明                 |
| --------- | --------------------------- | -- | ----------- | ------------------ |
| `images`  | 1-3 个文件、base64 字符串或 URL 的数组 | 是  | -           | 第一张是基础图像；其余为编辑层或遮罩 |
| `prompt`  | string                      | 是  | -           | 关于如何组合或编辑层的文本指令    |
| `modelId` | string                      | 否  | `qwen-edit` | 编辑模型 ID            |

### `/image/background-remove`

| 参数          | 类型             | 必填                        | 说明           |
| ----------- | -------------- | ------------------------- | ------------ |
| `image`     | 文件或 base64 字符串 | `image` 或 `image_url` 二选一 | 要抠出的源图像      |
| `image_url` | string         | `image` 或 `image_url` 二选一 | 要抠出的公开图像 URL |

***

## 支持的输入格式

| 端点                         | JSON 输入         | Multipart 输入 | 输出          |
| -------------------------- | --------------- | ------------ | ----------- |
| `/image/edit`              | Base64 字符串或 URL | 文件上传         | `image/png` |
| `/image/multi-edit`        | Base64 字符串或 URL | 文件上传         | `image/png` |
| `/image/background-remove` | Base64 字符串或 URL | 文件上传         | `image/png` |

对于编辑端点，图像尺寸必须至少为 `65536` 像素且不超过 `33177600` 像素。上传文件必须小于 `25MB`。

***

## 模型和定价

默认编辑模型是 `qwen-edit`，价格为**每次编辑 \$0.04**。其他具备编辑能力的模型可能有不同的定价和限制。

请参阅：

* [图像定价](/overview/pricing)
* 带有 `type=inpaint` 的 [Models API](/api-reference/endpoint/models/list)

***

## 错误

| 状态    | 含义          | 应对方式                                                          |
| ----- | ----------- | ------------------------------------------------------------- |
| `400` | 请求参数无效      | 检查图像数量、字段名和输入格式                                               |
| `401` | 身份验证失败      | 检查您的 API 密钥                                                   |
| `402` | 余额不足        | 在 [venice.ai/settings/api](https://venice.ai/settings/api) 充值 |
| `415` | 内容类型无效      | 正确使用 JSON 或 multipart form-data                               |
| `429` | 速率限制超出或模型过载 | 使用退避重试；查看 `Retry-After` 请求头                                   |
| `500` | 推理处理失败      | 重试请求                                                          |
| `503` | 模型容量已满      | 短暂延迟后重试                                                       |

<Note>
  某些编辑模型的内容政策比图像生成模型更严格。例如，`qwen-edit` 会拒绝涉及露骨色情图像、性化未成年人或真实暴力的请求。
</Note>

***

## 相关工作流

* 如果您从文本而非现有图像开始，请使用[图像生成](/guides/media/image-generation)。
* 使用[图像模型](/models/image)比较生成、编辑和增强模型家族。
* 使用 [Image Edit API](/api-reference/endpoint/image/edit)、[Multi-Edit API](/api-reference/endpoint/image/multi-edit) 和 [Background Remove API](/api-reference/endpoint/image/background-remove) 了解完整 schema 细节。