Image Editing

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 an image file. For cutouts, /image/background-remove returns a transparent PNG.

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

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 multiple reference images (limit varies by model)	Compositing and multi-reference edits
`POST /image/background-remove`	Remove the background from an image	Transparent cutouts for products, portraits, and assets

Venice has no OpenAI-compatible /images/edits endpoint, so OpenAI SDK calls such as client.images.edit() return 404. Send edits to /image/edit instead.

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 to condition the edit on additional reference images.
Use /image/background-remove when you only want a clean foreground subject with transparency.

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

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 for behavior, pricing, and response-header details.

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:

POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "firered-image-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. The format is PNG for 1K edits and JPEG for 2K and 4K edits, or PNG at any resolution when transparent_background is true. Set output_format to jpeg, png, or webp to choose it explicitly. The edit endpoints have no response_format parameter, so they can’t return the image as base64 JSON. If you need base64, encode the response bytes yourself.

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": "firered-image-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)

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: "firered-image-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);

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": "firered-image-edit",
    "prompt": "Colorize this black and white portrait naturally",
    "image": "https://example.com/portrait-bw.jpg"
  }'

Step 2: Use multi-edit with reference images

/image/multi-edit accepts multiple images, and the cap is model-specific. Read model_spec.constraints.maxInputImages from GET /models?type=inpaint to get the cap for a given model. When the field is absent, the cap is 3, or 1 when combineImages is false. The first image is the base image. The remaining images are additional references that condition the edit.

The public endpoint has no mask channel. Additional images act as references across the whole image, not as region maps — there is no mask parameter, and sending one returns a 400. Prompt precisely to constrain where the edit lands.

This is the better choice when you want to:

combine an existing composition with an additional reference image
give the model examples of the style, object, or texture to apply
constrain the edit more tightly than a single-image prompt can

JSON request:

{
  "modelId": "firered-image-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-reference.png"
  ]
}

Multipart request:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=firered-image-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o multi-edited.png

Like /image/edit, the response body is raw image data, and the output format follows the same rules.

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

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:

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 supply an additional reference image showing the desired result, then describe the intended change precisely in the prompt.

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:

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:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "[email protected]" \
  -o cutout.png

Use background removal for:

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

If you are generating or editing the image anyway, you can skip this second call: /image/generate, /image/edit, and /image/multi-edit accept transparent_background: true on supported models and return the alpha channel directly. See Transparent Background Images for the comparison.

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	`firered-image-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, such as `1K`, `2K`, or `4K`. Supported values vary by model
`output_format`	string	No	inferred	`jpeg`, `png`, or `webp`. When omitted, PNG for 1K edits and JPEG for 2K and 4K edits, or PNG at any resolution when `transparent_background` is `true`
`enhance_prompt`	boolean	No	`false`	Analyze the input image and rewrite the edit instruction before inference
`disable_prompt_optimization_thinking`	boolean	No	model default	Skip the model’s prompt-optimization thinking step for faster generation. Only supported by models with `supportsOptimizePromptThinking`; ignored by others
`safe_mode`	boolean	No	`true`	Blur adult content in the edited result. Set to `false` to disable blurring.
`transparent_background`	boolean	No	`false`	Return the edit with a real alpha channel. Requires a model with `supportsTransparentBackground: true` and `output_format` `png` or `webp` (inferred as PNG when omitted). See Transparent Background Images
`modelId`	string	Deprecated	-	Deprecated alias for `model`

`/image/multi-edit`

Parameter	Type	Required	Default	Description
`images`	array of files, base64 strings, or URLs	Yes	-	First image is the base image; the rest are additional references. Maximum is model-specific — see `model_spec.constraints.maxInputImages`
`prompt`	string	Yes	-	Text instructions for how to combine or edit the images
`modelId`	string	No	`firered-image-edit`	Edit model ID
`resolution`	string	No	`1K`	Resolution tier for the output image, such as `1K`, `2K`, or `4K`. Supported values vary by model
`quality`	string	No	model default	`low`, `medium`, or `high` on models that list `qualities` in `model_spec.constraints`. Higher values can increase the request charge
`output_format`	string	No	inferred	`jpeg`, `png`, or `webp`. Same inference rules as `/image/edit`
`enhance_prompt`	boolean	No	`false`	Analyze the input images and rewrite the edit instruction before inference
`disable_prompt_optimization_thinking`	boolean	No	model default	Skip the model’s prompt-optimization thinking step for faster generation. Only supported by models with `supportsOptimizePromptThinking`; ignored by others
`safe_mode`	boolean	No	`true`	Blur adult content in the edited result. Set to `false` to disable blurring.
`transparent_background`	boolean	No	`false`	Return the composed result with a real alpha channel. Same model and format rules as `/image/edit`

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

/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 because model is not a recognized field.

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, so send safe_mode: false to receive unblurred output:

{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}

Unblurred adult (NSFW) output is available to every API user. You don’t need a Pro subscription, and the mature filter setting in the Venice app does not affect image requests made through the API. Content policies vary by edit model and apply 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`
`/image/multi-edit`	Base64 strings or URLs	File uploads	`image/png`, `image/jpeg`, or `image/webp`
`/image/background-remove`	Base64 string or URL	File upload	`image/png`

For edit endpoints, images must be at least 256×256 pixels, and the total pixel count must not exceed 33,177,600 (8K resolution). Uploaded files must be under 25MB.

Models and pricing

The default edit model is firered-image-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
Models API 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
`413`	File too large	Keep uploaded files under 25 MB
`415`	Invalid content type (`/image/multi-edit` only; the other endpoints return `400`)	Use JSON or multipart form-data correctly
`422`	Content policy violation or input image too large	Adjust the prompt or reduce the image dimensions
`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

Some edit models have stricter content policies than image generation models. Requests that violate the selected model’s policy are rejected with 422.

Use Image Generation when you’re starting from text instead of an existing image.
Use Prompt Enhancement to learn how vision-aware edit rewriting works.
Use Image Models to compare generation, edit, and enhancement model families.
Use Image Edit API, Multi-Edit API, and Background Remove API for full schema details.

Docs

Getting Started

Text & Chat

Image

Video

Audio

Search & RAG

Agents & Integrations

Coding Tools

Agent Tooling

SDKs & Frameworks

Endpoints

When to use which endpoint

Step 1: Edit a single image

Step 2: Use multi-edit with reference images

Inpainting tips

Step 3: Remove the background

Request Parameters

`/image/edit`

`/image/multi-edit`

`/image/background-remove`

Adult content and safe mode

Supported input formats

Models and pricing

Errors

​Endpoints

​When to use which endpoint

​Step 1: Edit a single image

​Step 2: Use multi-edit with reference images

​Inpainting tips

​Step 3: Remove the background

​Request Parameters

​/image/edit

​/image/multi-edit

​/image/background-remove

​Adult content and safe mode

​Supported input formats

​Models and pricing

​Errors

​Related Workflows

Endpoints

When to use which endpoint

Step 1: Edit a single image

Step 2: Use multi-edit with reference images

Inpainting tips

Step 3: Remove the background

Request Parameters

`/image/edit`

`/image/multi-edit`

`/image/background-remove`

Adult content and safe mode

Supported input formats

Models and pricing

Errors

Related Workflows