venice-image-edit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Venice Image Editing

Four endpoints, all operating on existing images:

| Endpoint | Purpose |
|---|---|
| `POST /image/edit` | Transform one image with a text prompt. JSON or `multipart/form-data`. |
| `POST /image/multi-edit` | Composite / layer several images with a single prompt. JSON or `multipart/form-data`. |
| `POST /image/upscale` | Upscale 2×–4×. JSON or `multipart/form-data`. |
| `POST /image/background-remove` | Produce a transparent PNG cutout. JSON or `multipart/form-data`. |

For text-to-image generation, see [`venice-image-generate`](../venice-image-generate/SKILL.md).

## Shared rules

| | `/image/edit` | `/image/multi-edit` | `/image/upscale` | `/image/background-remove` |
|---|---|---|---|---|
| JSON input | `image`: raw base64, data URI, or `http(s)://` URL | `images[]`: raw base64, data URI, or `http(s)://` URLs | `image`: raw base64 only | `image` (base64 / data URI) **or** `image_url` |
| Multipart input | one file in `image` | files in repeated `images` parts | one file in `image` | one file in `image` |
| Min size | ≥ 65,536 px total and ≥ 64 px per side | same | same | not checked by Venice |
| Max size | ≤ 33,177,600 px (7680×4320) | same | output ≤ 16,777,216 px (4096×4096) | not checked by Venice |
| Response | edited image bytes (PNG/JPEG/WebP) | edited image bytes | `image/png` | `image/png` with alpha |
| Model | `model` (default `firered-image-edit`) | `modelId` (default `firered-image-edit`) | fixed: `upscaler` | fixed: `bria-bg-remover` |

- Accepted input formats: JPEG, PNG, WebP, HEIF/HEIC, AVIF. SVG is rejected. Background-remove doesn't pre-validate the format; it passes the image straight to the model.
- Files must be < **25 MB** (multipart files over 25 MB return `413`). URLs fetched for edit and multi-edit are capped at 25 MB too. JSON bodies over 35 MB (for example a large base64 image) return `413`.
- URLs are fetched server-side and must be publicly reachable. Private, internal, and metadata hosts are blocked (`400`).
- All four endpoints return the image as **binary**, never JSON. There is no `return_binary` field (that flag only exists on `/image/generate`).
- JSON bodies on edit, multi-edit, and background-remove are **strict**: unknown fields are a `400`. `/image/upscale` ignores unknown fields.
- Edit, multi-edit, and background-remove accept an optional `anon_user_id` (printable ASCII, ≤ 128 chars, no `||`) for upstream end-user attribution.

## Choosing an edit model

```bash
curl "https://api.venice.ai/api/v1/models?type=inpaint"
```

Per model, read `model_spec.constraints`:

- `aspectRatios[]` — allowed `aspect_ratio` values. Not every model lists `auto` (e.g. `gpt-image-2-edit`, `qwen-image-2-edit`); `wan-2-7-pro-edit` only accepts `auto`.
- `resolutions[]` + `defaultResolution` — present when the model accepts `resolution`.
- `qualities[]` + `defaultQuality` — present when the model accepts `quality` (multi-edit only).
- `promptCharacterLimit` — enforced per model (1,500 for `firered-image-edit`, up to 32,768 for Nano Banana edits).
- `combineImages` — `false` means the model takes exactly one input image.
- `maxInputImages` — input-image cap for multi-edit. When it's absent and `combineImages` is `true`, the cap is **3**.
- `supportsOptimizePromptThinking` — whether `disable_prompt_optimization_thinking` does anything.

Pricing: `pricing.inpaint.usd` per edit, `pricing.resolutions[tier]` / `pricing.quality[tier][level]` on tiered models, and `pricing.inputImages` (`included` + `additional.usd` per extra image) on models that charge per additional input image. When `included` is `0` (e.g. `qwen-image-3-edit`, the Grok Imagine edits), every input image is surcharged, including the single image on `/image/edit`.

Representative edit IDs today (the list changes often, so read it from `/models`): `firered-image-edit` (default), `qwen-image-3-edit`, `qwen-image-3-pro-edit`, `nano-banana-2-edit`, `nano-banana-pro-edit`, `gpt-image-2-5-flare-edit`, `gpt-image-2-5-sunburst-edit`, `gpt-image-2-edit`, `seedream-v5-pro-edit`, `seedream-v5-lite-edit`, `muse-image-edit`, `flux-2-max-edit`, `grok-imagine-image-2-0-edit`, `luma-uni-1-edit` (single image only). The old `qwen-edit` ID still works as an alias and runs `qwen-edit-uncensored`.

## `/image/edit`

Edit one image with a short, descriptive prompt.

```bash
curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3-edit",
    "prompt": "Change the color of the sky to a sunrise",
    "image": "https://example.com/photo.jpg",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "safe_mode": true
  }'
```

Multipart equivalent: send `image` as a file part and the other fields as text parts (`-F image=@photo.jpg -F prompt=... -F model=...`). Only one file is allowed.

| Field | Notes |
|---|---|
| `model` | Default `firered-image-edit`. Must be an ID from `GET /models?type=inpaint` (otherwise `400 Invalid model id`). `modelId` is still accepted as a deprecated alias; `model` wins if both are sent. |
| `prompt` | Required. ≤ the model's `promptCharacterLimit` (hard ceiling 32,768). Short and specific works best. |
| `image` | Required. See the shared rules for accepted input formats. |
| `aspect_ratio` | Optional: `auto`, `1:1`, `3:2`, `16:9`, `21:9`, `9:16`, `2:3`, `3:4`, `4:3`, `4:5`. Must be in the model's `constraints.aspectRatios`, or you get `400`. Omit it (or send `auto` where listed) to infer from the input image. |
| `resolution` | Optional, e.g. `"1K"`, `"2K"`, `"4K"`. Must be in the model's `constraints.resolutions`. **Sending any `resolution` to a model without resolutions is a `400` on this endpoint.** Defaults to the model's `defaultResolution`. |
| `output_format` | Optional `jpeg` (or `jpg`) \| `png` \| `webp`. When omitted: PNG for 1K (or no resolution), JPEG for 2K/4K. |
| `enhance_prompt` | Optional bool, default `false`. Rewrites your prompt against the input image before editing. Adds up to ~30 s and a $0.04 charge when a rewrite is produced. The rewritten prompt comes back URL-encoded in the `x-venice-enhanced-prompt` response header. |
| `disable_prompt_optimization_thinking` | Optional bool. Only honored by models with `supportsOptimizePromptThinking: true`; ignored elsewhere. |
| `safe_mode` | Default `true`; blurs adult content. |

There is **no `quality` field** on `/image/edit`; sending it is a `400`, and quality-tier models are billed at their `defaultQuality`. To pick a quality tier (GPT Image models, `ideogram-v4-5-edit`), use `/image/multi-edit` with a single image.

Good prompts: *"remove the tree"*, *"add sunglasses to the cat"*, *"make the sky a vivid orange sunrise"*.

## `/image/multi-edit`

Combine several images into one with a prompt. The **first image is the base**; the rest are layers or references. Minimum 1 image. The maximum is per model: `constraints.maxInputImages` (6 on most current models), 3 if that field is absent, and 1 when `combineImages` is `false`.

> **Field name:** `/image/multi-edit` takes **`modelId`**, not `model`. Sending `model` is a `400` (unknown field).

### JSON (base64, data URIs, or URLs)

```json
{
  "modelId": "nano-banana-2-edit",
  "prompt": "Place the person from image 2 onto the beach in image 1",
  "images": [
    "https://example.com/beach.jpg",
    "data:image/png;base64,iVBOR..."
  ],
  "resolution": "2K",
  "safe_mode": true
}
```

### Multipart (file upload)

```
POST /image/multi-edit
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="modelId"

nano-banana-2-edit
--boundary

From veniceai/skills, MIT.

More from veniceai/skills