> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-f533effe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Editing

> Edit, inpaint, and remove backgrounds from images with the Venice API using /image/edit, multi-edit layers, masks, and safe mode controls.

Image editing on Venice is synchronous. Send your source image to `/image/edit` or `/image/multi-edit` and the edited result comes back in the same response as a raw image file. For cutouts, `/image/background-remove` returns a transparent PNG.

<Warning>
  The image edit endpoints are experimental and model-specific behavior may change over time.
</Warning>

## Endpoints

| Endpoint                        | Purpose                             | Best for                                                |
| ------------------------------- | ----------------------------------- | ------------------------------------------------------- |
| `POST /image/edit`              | Edit a single image with a prompt   | General edits and prompt-driven inpainting              |
| `POST /image/multi-edit`        | Edit using 1-3 layered images       | More controlled edits with masks or overlays            |
| `POST /image/background-remove` | Remove the background from an image | Transparent cutouts for products, portraits, and assets |

<Note>
  Venice does not provide an OpenAI-compatible `/images/edits` endpoint. The only OpenAI-compatible image path is `POST /images/generations` for generation. For editing, use the native `POST /image/edit` endpoint.
</Note>

## When to use which endpoint

* Use `/image/edit` when you have one source image and want to change, remove, or restyle part of it with a prompt.
* Use `/image/multi-edit` when you need extra control from masks, overlays, or reference layers.
* Use `/image/background-remove` when you only want a clean foreground subject with transparency.

<Note>
  For inpainting, use `/image/edit` or `/image/multi-edit`. The old `inpaint` parameter on `/image/generate` is deprecated.
</Note>

<Tip>
  Set `enhance_prompt: true` on either edit endpoint to have a vision-aware enhancer analyze the input image or images and rewrite your instruction before editing. See [Prompt Enhancement](/guides/media/prompt-enhancement) for behavior, pricing, and response-header details.
</Tip>

## Step 1: Edit a single image

Single-image edit is the simplest inpainting flow. Send one image plus a short prompt such as "remove the sign", "change the sky to sunrise", or "replace the background with a studio backdrop".

**Request:**

```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"
}
```

**Response (200):**
The response body is raw image binary data. Save it directly to a file. See [Response format](#response-format) for how `output_format` controls the file type.

<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>

## Step 2: Use multi-edit for masks or layered inpainting

`/image/multi-edit` accepts up to three images. The first image is the base image. The remaining images are treated as edit layers or masks, which gives you more control than prompt-only editing.

This is the better choice when you want to:

* target a specific region with a mask
* combine an existing composition with an overlay
* constrain the edit more tightly than a single-image prompt can

**JSON request:**

```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 request:**

```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
```

Like `/image/edit`, the response body is raw image data.

<Note>
  `/image/multi-edit` currently uses the `modelId` field rather than `model` in the request schema.
</Note>

***

## Inpainting tips

Prompt-based inpainting works best when the instruction is short and local:

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

For broader scene changes, describe what should stay the same:

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

If the edit keeps affecting the wrong area, switch from `/image/edit` to `/image/multi-edit` and provide a mask or overlay layer.

***

## Step 3: Remove the background

Use `/image/background-remove` when you want the foreground subject isolated on a transparent background. This endpoint returns a PNG with alpha transparency.

**Using an image 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"
  }'
```

**Using a local file upload:**

```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
```

Use background removal for:

* ecommerce product photos
* profile photos and portraits
* assets you plan to place over a new background

***

## Response format

`/image/edit` and `/image/multi-edit` always return the edited image as raw binary data (`image/png`, `image/jpeg`, or `image/webp`). The edit endpoints do not accept a `response_format` parameter. There is no `b64_json` or `url` option like on `/images/generations`. If you need the result inside JSON, base64-encode the binary response in your own code.

Control the file type with `output_format`:

* `output_format` accepts `jpeg`, `jpg`, `png`, or `webp`.
* When omitted, the format is inferred from `resolution`: PNG for 1K edits and JPEG for 2K and 4K edits.

***

## Request Parameters

### `/image/edit`

| Parameter        | Type                        | Required   | Default                    | Description                                                                             |
| ---------------- | --------------------------- | ---------- | -------------------------- | --------------------------------------------------------------------------------------- |
| `image`          | file, base64 string, or URL | Yes        | -                          | Source image to edit                                                                    |
| `prompt`         | string                      | Yes        | -                          | Text instructions for the edit                                                          |
| `model`          | string                      | No         | `qwen-edit`                | Edit model ID                                                                           |
| `aspect_ratio`   | string                      | No         | model default              | Output ratio for models that support it                                                 |
| `resolution`     | string                      | No         | `1K`                       | Resolution tier for the output image (`1K`, `2K`, `4K`); supported values vary by model |
| `output_format`  | string                      | No         | inferred from `resolution` | Output file type: `jpeg`, `jpg`, `png`, or `webp`                                       |
| `enhance_prompt` | boolean                     | No         | `false`                    | Analyze the input image and rewrite the edit instruction before inference               |
| `safe_mode`      | boolean                     | No         | `true`                     | Blur adult content in the edited result. Set to `false` to disable blurring.            |
| `modelId`        | string                      | Deprecated | -                          | Deprecated alias for `model`                                                            |

### `/image/multi-edit`

| Parameter        | Type                                        | Required | Default                    | Description                                                                             |
| ---------------- | ------------------------------------------- | -------- | -------------------------- | --------------------------------------------------------------------------------------- |
| `images`         | array of 1-3 files, base64 strings, or URLs | Yes      | -                          | First image is the base image; the rest are edit layers or masks                        |
| `prompt`         | string                                      | Yes      | -                          | Text instructions for how to combine or edit the layers                                 |
| `modelId`        | string                                      | No       | `qwen-edit`                | Edit model ID                                                                           |
| `resolution`     | string                                      | No       | `1K`                       | Resolution tier for the output image (`1K`, `2K`, `4K`); supported values vary by model |
| `output_format`  | string                                      | No       | inferred from `resolution` | Output file type: `jpeg`, `jpg`, `png`, or `webp`                                       |
| `enhance_prompt` | boolean                                     | No       | `false`                    | Analyze the input images and rewrite the edit instruction before inference              |
| `safe_mode`      | boolean                                     | No       | `true`                     | Blur adult content in the edited result. Set to `false` to disable blurring.            |

### `/image/background-remove`

| Parameter   | Type                  | Required                      | Description                 |
| ----------- | --------------------- | ----------------------------- | --------------------------- |
| `image`     | file or base64 string | One of `image` or `image_url` | Source image to cut out     |
| `image_url` | string                | One of `image` or `image_url` | Public image URL to cut out |

<Note>
  `/image/background-remove` uses a fixed internal model. It does not accept a `model` field. Sending one (for example `"model": "bria-bg-remover"`) returns `400 invalid model id`.
</Note>

### Adult content and safe mode

Both `/image/edit` and `/image/multi-edit` accept `safe_mode` (default: `true`). When enabled, adult content in the edited output is blurred. Set `safe_mode: false` to receive unblurred output:

```json theme={"system"}
{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}
```

The default `qwen-edit` model still blocks explicit sexual imagery and real-world violence regardless of `safe_mode`. For uncensored editing, use `qwen-edit-uncensored`.

The moderation-name difference between endpoints trips people up:

| Endpoint                                                  | Field to disable blur |
| --------------------------------------------------------- | --------------------- |
| `POST /image/edit`, `POST /image/multi-edit`              | `safe_mode: false`    |
| `POST /image/generate` (native generation)                | `safe_mode: false`    |
| `POST /images/generations` (OpenAI-compatible generation) | `moderation: "low"`   |

Passing `safe_mode` to `/images/generations` returns `400` with `Unrecognized key(s) in object: 'safe_mode'`.

***

## Supported input formats

| Endpoint                   | JSON input             | Multipart input | Output                                                         |
| -------------------------- | ---------------------- | --------------- | -------------------------------------------------------------- |
| `/image/edit`              | Base64 string or URL   | File upload     | `image/png`, `image/jpeg`, or `image/webp` per `output_format` |
| `/image/multi-edit`        | Base64 strings or URLs | File uploads    | `image/png`, `image/jpeg`, or `image/webp` per `output_format` |
| `/image/background-remove` | Base64 string or URL   | File upload     | `image/png`                                                    |

For edit endpoints, image dimensions must be at least `65536` pixels and no more than `33177600` pixels. Uploaded files must be under `25MB`.

***

## Models and pricing

The default edit model is `qwen-edit`, priced at **$0.04 per edit**. Other edit-capable models may have different pricing and constraints. Prompt enhancement adds **$0.04 per applied rewrite** to the edit price.

See:

* [Image pricing](/overview/pricing)
* [Models API](/api-reference/endpoint/models/list) with `type=inpaint`

***

## Errors

| Status | Meaning                                 | Action                                                                                                      |
| ------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters              | Check image count, field names, and input format                                                            |
| `401`  | Authentication failed                   | Check your API key                                                                                          |
| `402`  | Insufficient balance                    | Add credits at [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) |
| `415`  | Invalid content type                    | Use JSON or multipart form-data correctly                                                                   |
| `429`  | Rate limit exceeded or model overloaded | Retry with backoff; check `Retry-After` header                                                              |
| `500`  | Inference processing failed             | Retry the request                                                                                           |
| `503`  | Model at capacity                       | Retry after a short delay                                                                                   |

<Note>
  Some edit models have stricter content policies than image generation models. For example, `qwen-edit` blocks requests involving explicit sexual imagery, sexualized minors, or real-world violence.
</Note>

***

## Related Workflows

* Use [Image Generation](/guides/media/image-generation) when you're starting from text instead of an existing image.
* Use [Prompt Enhancement](/guides/media/prompt-enhancement) to learn how vision-aware edit rewriting works.
* Use [Image Models](/models/image) to compare generation, edit, and enhancement model families.
* Use [Image Edit API](/api-reference/endpoint/image/edit), [Multi-Edit API](/api-reference/endpoint/image/multi-edit), and [Background Remove API](/api-reference/endpoint/image/background-remove) for full schema details.