Venice Image Editing
Four endpoints, all operating on existing images:
| Endpoint |
Purpose |
POST /image/edit |
Transform one image with a text prompt. |
POST /image/multi-edit |
Composite / layer several images with a single prompt. Also has a multipart/form-data variant. |
POST /image/upscale |
Upscale 2× or 4×. |
POST /image/background-remove |
Produce a transparent cutout. |
For text-to-image generation, see venice-image-generate.
Shared rules
- Input image accepts base64 string, file upload (multipart for
/image/multi-edit), or HTTPS URL (for edit + multi-edit + background-remove).
- File size < 25 MB. Image dimensions must be between 65,536 (256×256 equivalent) and 33,177,600 pixels (~5,761×5,761). Upscale caps at 16,777,216 pixels after scaling.
- HTTPS URLs must be publicly reachable from Venice's network.
- All four endpoints return the image as binary, never JSON. There is no
return_binary field on edit / multi-edit / upscale / background-remove (that flag only exists on /image/generate). /image/edit and /image/multi-edit return image/png, image/jpeg, or image/webp depending on output_format; /image/upscale and /image/background-remove always return image/png.
/image/edit
Edit one image with a short, descriptive prompt.
curl https://api.venice.ai/api/v1/image/edit \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "firered-image-edit",
"prompt": "Change the color of the sky to a sunrise",
"image": "iVBORw0KGgoAAAANSUhEUg...",
"aspect_ratio": "16:9",
"safe_mode": true
}'
| Field |
Notes |
model |
Default firered-image-edit. See GET /models?type=inpaint for edit-capable models. modelId is accepted for backwards compatibility but deprecated on /image/edit — prefer model. |
prompt |
Required, ≤ 32 768 chars (usually 1500 is plenty). Short & specific works best. |
image |
Required. Base64 string, file upload, or https:// URL. |
aspect_ratio |
Optional: auto, 1:1, 3:2, 16:9, 21:9, 9:16, 2:3, 3:4, 4:5. Supported values vary per model — check constraints on GET /models. |
resolution |
Optional tier, e.g. "1K", "2K", "4K". Defaults to "1K". Supported values vary per model. |
output_format |
Optional jpeg | png | webp. When omitted, inferred from resolution: PNG for 1K, JPEG for 2K/4K. |
enhance_prompt |
Optional bool, default false. Rewrites your prompt against the input image before editing. Costs extra credits and adds up to ~30 s. The rewritten prompt comes back URL-encoded in the x-venice-enhanced-prompt response header. |
disable_prompt_optimization_thinking |
Optional bool. Skips the model's prompt-optimization thinking step for speed. Only honored by models with supportsOptimizePromptThinking; ignored elsewhere. |
safe_mode |
Default true; blurs adult content. |
Good prompts: "remove the tree", "add sunglasses to the cat", "make the sky a vivid orange sunrise".
Edit-capable model IDs change often. Read them from GET /models?type=inpaint
rather than pinning a literal, and note that older IDs like qwen-edit have
been retired in favor of qwen-image-2-edit and friends.
/image/multi-edit
Combine several images into one with a prompt. The first image is the base; the rest are layers / masks / references. The minimum is 1 image and the maximum is model-specific — read capabilities.maxInputImages from GET /models.
Field name: /image/multi-edit takes modelId, not model. This is the only image endpoint that uses modelId as the primary field name.
JSON (base64 or URLs)
{
"modelId": "firered-image-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..."
],
"safe_mode": true
}
Multipart (file upload)
POST /image/multi-edit
Content-Type: multipart/form-data
--boundary
Content-Disposition: form-data; name="modelId"
firered-image-edit
--boundary
Content-Disposition: form-data; name="prompt"
Place the person from image 2 onto the beach in image 1
--boundary
Content-Disposition: form-data; name="images"; filename="base.jpg"
Content-Type: image/jpeg
<bytes>
--boundary
Content-Disposition: form-data; name="images"; filename="subject.png"
Content-Type: image/png
<bytes>
--boundary--
| Field |
Notes |
modelId |
Required field name (multi-edit does not accept model). Default firered-image-edit. |
prompt |
Required, ≤ 32 768 chars. |
images |
Required. Minimum 1; maximum is model-specific (capabilities.maxInputImages). JSON variant accepts base64 or HTTPS URLs; multipart variant accepts raw file parts. |
aspect_ratio |
Optional; inferred from the first image when set to auto or omitted. |
resolution |
Optional tier, e.g. "1K", "2K", "4K". Defaults to "1K". |
output_format |
Optional jpeg | png | webp. Inferred from resolution when omitted. |
quality |
Optional low | medium | high for models that support it (e.g. GPT Image 2). Higher values can raise the charge. |
enhance_prompt |
Optional bool, default false. Same behavior and x-venice-enhanced-prompt header as /image/edit. |
disable_prompt_optimization_thinking |
Optional bool. |
safe_mode |
Default true. |
/image/upscale
Upscale 2× or 4×. This endpoint has three fields.
Breaking change: /image/upscale no longer accepts enhance,
enhanceCreativity, enhancePrompt, or replication, and no longer accepts
scale: 1. The enhancer knobs were replaced by a single creativity field
with a much narrower range. If you are sending the old fields, drop them.
curl https://api.venice.ai/api/v1/image/upscale \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "iVBORw0KGgo...",
"scale": 4,
"creativity": 0.01
}'
| Field |
Type |
Default |
Notes |
image |
base64, file upload |
— |
Required. Must be ≥ 65 536 px² to start, < 25 MB, and ≤ 16 777 216 px after scaling. |
scale |
number, 2 or 4 |
2 |
Must be either 2 or 4. 4 on large images is dynamically reduced to stay within the 16 MP output cap. |
creativity |
number, 0–0.02 |
0.01 |
How much detail and texture the upscaler adds. Higher adds more; lower stays closer to the source. Values outside the range are clamped, so 0.5 behaves as 0.02, not as "half creative". Nullable. |
Also available as multipart/form-data. Response is the upscaled image as
binary image/png.
/image/background-remove
Produce a transparent PNG cutout.
# With base64
curl https://api.venice.ai/api/v1/image/background-remove \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "iVBOR..."}'
# With a URL
curl https://api.venice.ai/api/v1/image/background-remove \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/photo.jpg"}'
Send either image (base64 / file) or image_url. Response is image/png with alpha channel.
Error behavior (all four endpoints)
| Code |
Cause |
400 |
Bad params — image dims out of range, file too large, unknown model, unsupported aspect ratio for the model, content-policy refusal. |
401 |
Auth failed. (Pro-gating on these paths surfaces as 400 / 402 depending on condition.) |
402 |
Insufficient balance. Bearer: plain { "error": "Insufficient balance" }. x402: PAYMENT_REQUIRED body + PAYMENT-REQUIRED header. |
415 |
Wrong Content-Type (e.g. JSON sent to a multipart endpoint, or vice versa). |
429 |
Rate limited. |
500 / 503 |
Inference / capacity issue — retry with jitter. |
(413 and 422 are not documented for these image paths in the OpenAPI spec — a 413 from the platform may still appear if you exceed ingress limits, but treat 400 / 415 as the primary failure surface.)
Gotchas
/image/multi-edit images[] explicitly accepts data:image/...;base64,... URLs or plain base64. For /image/edit and /image/upscale, send base64 as a plain string unless the docs say otherwise — if your client adds a data: prefix and you get a 400, strip it.
- For multipart
/image/multi-edit, the field name is images and you send multiple parts with the same field name — order matters (base first).
- Field-name asymmetry:
/image/edit prefers model (modelId is a deprecated alias). /image/multi-edit accepts only modelId. Get the name right per endpoint — sending the wrong one is a 400.
/image/upscale with scale=4 on a large input is silently clamped to stay under 16 MP.
creativity on /image/upscale is not the old enhanceCreativity under a new name. Its usable range is 0 to 0.02, so port enhanceCreativity: 0.5 as creativity: 0.02 (the maximum), not as 0.5.
enhance_prompt on edit / multi-edit bills extra credits whenever a rewrite is produced. Leave it off for latency-sensitive or cost-sensitive calls.
safe_mode: true can blur otherwise valid inputs if the source image trips content classifiers; switch to false (and handle the legal/ToS consequences yourself) when you control the input.
/image/background-remove takes either image or image_url, not both.
1---2name: venice-image-edit3description: Transform existing images with Venice. Covers POST /image/edit (prompt-driven single-image edit), /image/multi-edit (compose multiple images), /image/upscale (2x or 4x upscale), and /image/background-remove. Accepts base64, file upload, or HTTPS URL.4metadata:5 source: https://skillmd.com/skills/veniceai/venice-image-edit6---78# Venice Image Editing910Four endpoints, all operating on existing images:1112| Endpoint | Purpose |13|---|---|14| `POST /image/edit` | Transform one image with a text prompt. |15| `POST /image/multi-edit` | Composite / layer several images with a single prompt. Also has a `multipart/form-data` variant. |16| `POST /image/upscale` | Upscale 2× or 4×. |17| `POST /image/background-remove` | Produce a transparent cutout. |1819For text-to-image generation, see [`venice-image-generate`](../venice-image-generate/SKILL.md).2021## Shared rules2223- Input image accepts **base64 string**, **file upload** (multipart for `/image/multi-edit`), or **HTTPS URL** (for edit + multi-edit + background-remove).24- File size < **25 MB**. Image dimensions must be between **65,536** (256×256 equivalent) and **33,177,600** pixels (~5,761×5,761). Upscale caps at **16,777,216** pixels after scaling.25- HTTPS URLs must be publicly reachable from Venice's network.26- All four endpoints return the image as **binary**, never JSON. There is no `return_binary` field on edit / multi-edit / upscale / background-remove (that flag only exists on `/image/generate`). `/image/edit` and `/image/multi-edit` return `image/png`, `image/jpeg`, or `image/webp` depending on `output_format`; `/image/upscale` and `/image/background-remove` always return `image/png`.2728## `/image/edit`2930Edit one image with a short, descriptive prompt.3132```bash33curl https://api.venice.ai/api/v1/image/edit \34 -H "Authorization: Bearer $VENICE_API_KEY" \35 -H "Content-Type: application/json" \36 -d '{37 "model": "firered-image-edit",38 "prompt": "Change the color of the sky to a sunrise",39 "image": "iVBORw0KGgoAAAANSUhEUg...",40 "aspect_ratio": "16:9",41 "safe_mode": true42 }'43```4445| Field | Notes |46|---|---|47| `model` | Default `firered-image-edit`. See `GET /models?type=inpaint` for edit-capable models. `modelId` is accepted for backwards compatibility but deprecated on `/image/edit` — prefer `model`. |48| `prompt` | Required, ≤ 32 768 chars (usually 1500 is plenty). Short & specific works best. |49| `image` | Required. Base64 string, file upload, or `https://` URL. |50| `aspect_ratio` | Optional: `auto`, `1:1`, `3:2`, `16:9`, `21:9`, `9:16`, `2:3`, `3:4`, `4:5`. Supported values vary per model — check `constraints` on `GET /models`. |51| `resolution` | Optional tier, e.g. `"1K"`, `"2K"`, `"4K"`. Defaults to `"1K"`. Supported values vary per model. |52| `output_format` | Optional `jpeg` \| `png` \| `webp`. When omitted, inferred from `resolution`: PNG for 1K, JPEG for 2K/4K. |53| `enhance_prompt` | Optional bool, default `false`. Rewrites your prompt against the input image before editing. Costs extra credits and adds up to ~30 s. The rewritten prompt comes back URL-encoded in the `x-venice-enhanced-prompt` response header. |54| `disable_prompt_optimization_thinking` | Optional bool. Skips the model's prompt-optimization thinking step for speed. Only honored by models with `supportsOptimizePromptThinking`; ignored elsewhere. |55| `safe_mode` | Default `true`; blurs adult content. |5657Good prompts: *"remove the tree"*, *"add sunglasses to the cat"*, *"make the sky a vivid orange sunrise"*.5859Edit-capable model IDs change often. Read them from `GET /models?type=inpaint`60rather than pinning a literal, and note that older IDs like `qwen-edit` have61been retired in favor of `qwen-image-2-edit` and friends.6263## `/image/multi-edit`6465Combine several images into one with a prompt. The **first image is the base**; the rest are layers / masks / references. The minimum is 1 image and the maximum is model-specific — read `capabilities.maxInputImages` from `GET /models`.6667> **Field name:** `/image/multi-edit` takes **`modelId`**, not `model`. This is the only image endpoint that uses `modelId` as the primary field name.6869### JSON (base64 or URLs)7071```json72{73 "modelId": "firered-image-edit",74 "prompt": "Place the person from image 2 onto the beach in image 1",75 "images": [76 "https://example.com/beach.jpg",77 "data:image/png;base64,iVBOR..."78 ],79 "safe_mode": true80}81```8283### Multipart (file upload)8485```86POST /image/multi-edit87Content-Type: multipart/form-data8889--boundary90Content-Disposition: form-data; name="modelId"9192firered-image-edit93--boundary94Content-Disposition: form-data; name="prompt"9596Place the person from image 2 onto the beach in image 197--boundary98Content-Disposition: form-data; name="images"; filename="base.jpg"99Content-Type: image/jpeg100101<bytes>102--boundary103Content-Disposition: form-data; name="images"; filename="subject.png"104Content-Type: image/png105106<bytes>107--boundary--108```109110| Field | Notes |111|---|---|112| `modelId` | **Required field name** (multi-edit does not accept `model`). Default `firered-image-edit`. |113| `prompt` | Required, ≤ 32 768 chars. |114| `images` | Required. Minimum 1; maximum is model-specific (`capabilities.maxInputImages`). JSON variant accepts base64 or HTTPS URLs; multipart variant accepts raw file parts. |115| `aspect_ratio` | Optional; inferred from the **first** image when set to `auto` or omitted. |116| `resolution` | Optional tier, e.g. `"1K"`, `"2K"`, `"4K"`. Defaults to `"1K"`. |117| `output_format` | Optional `jpeg` \| `png` \| `webp`. Inferred from `resolution` when omitted. |118| `quality` | Optional `low` \| `medium` \| `high` for models that support it (e.g. GPT Image 2). Higher values can raise the charge. |119| `enhance_prompt` | Optional bool, default `false`. Same behavior and `x-venice-enhanced-prompt` header as `/image/edit`. |120| `disable_prompt_optimization_thinking` | Optional bool. |121| `safe_mode` | Default `true`. |122123## `/image/upscale`124125Upscale 2× or 4×. This endpoint has **three fields**.126127> **Breaking change:** `/image/upscale` no longer accepts `enhance`,128> `enhanceCreativity`, `enhancePrompt`, or `replication`, and no longer accepts129> `scale: 1`. The enhancer knobs were replaced by a single `creativity` field130> with a much narrower range. If you are sending the old fields, drop them.131132```bash133curl https://api.venice.ai/api/v1/image/upscale \134 -H "Authorization: Bearer $VENICE_API_KEY" \135 -H "Content-Type: application/json" \136 -d '{137 "image": "iVBORw0KGgo...",138 "scale": 4,139 "creativity": 0.01140 }'141```142143| Field | Type | Default | Notes |144|---|---|---|---|145| `image` | base64, file upload | — | Required. Must be ≥ 65 536 px² to start, < 25 MB, and ≤ 16 777 216 px after scaling. |146| `scale` | number, 2 or 4 | 2 | Must be either `2` or `4`. `4` on large images is dynamically reduced to stay within the 16 MP output cap. |147| `creativity` | number, 0–0.02 | 0.01 | How much detail and texture the upscaler adds. Higher adds more; lower stays closer to the source. Values outside the range are clamped, so `0.5` behaves as `0.02`, not as "half creative". Nullable. |148149Also available as `multipart/form-data`. Response is the upscaled image as150binary `image/png`.151152## `/image/background-remove`153154Produce a transparent PNG cutout.155156```bash157# With base64158curl https://api.venice.ai/api/v1/image/background-remove \159 -H "Authorization: Bearer $VENICE_API_KEY" \160 -H "Content-Type: application/json" \161 -d '{"image": "iVBOR..."}'162163# With a URL164curl https://api.venice.ai/api/v1/image/background-remove \165 -H "Authorization: Bearer $VENICE_API_KEY" \166 -H "Content-Type: application/json" \167 -d '{"image_url": "https://example.com/photo.jpg"}'168```169170Send **either** `image` (base64 / file) **or** `image_url`. Response is `image/png` with alpha channel.171172## Error behavior (all four endpoints)173174| Code | Cause |175|---|---|176| `400` | Bad params — image dims out of range, file too large, unknown model, unsupported aspect ratio for the model, content-policy refusal. |177| `401` | Auth failed. (Pro-gating on these paths surfaces as `400` / `402` depending on condition.) |178| `402` | Insufficient balance. Bearer: plain `{ "error": "Insufficient balance" }`. x402: `PAYMENT_REQUIRED` body + `PAYMENT-REQUIRED` header. |179| `415` | Wrong `Content-Type` (e.g. JSON sent to a multipart endpoint, or vice versa). |180| `429` | Rate limited. |181| `500` / `503` | Inference / capacity issue — retry with jitter. |182183(`413` and `422` are **not** documented for these image paths in the OpenAPI spec — a `413` from the platform may still appear if you exceed ingress limits, but treat `400` / `415` as the primary failure surface.)184185## Gotchas186187- `/image/multi-edit` `images[]` explicitly accepts `data:image/...;base64,...` URLs or plain base64. For `/image/edit` and `/image/upscale`, send base64 as a plain string unless the docs say otherwise — if your client adds a `data:` prefix and you get a `400`, strip it.188- For multipart `/image/multi-edit`, the field name is `images` and you send **multiple parts with the same field name** — order matters (base first).189- Field-name asymmetry: `/image/edit` prefers **`model`** (`modelId` is a deprecated alias). `/image/multi-edit` accepts **only `modelId`**. Get the name right per endpoint — sending the wrong one is a `400`.190- `/image/upscale` with `scale=4` on a large input is silently clamped to stay under 16 MP.191- `creativity` on `/image/upscale` is **not** the old `enhanceCreativity` under a new name. Its usable range is 0 to 0.02, so port `enhanceCreativity: 0.5` as `creativity: 0.02` (the maximum), not as `0.5`.192- `enhance_prompt` on edit / multi-edit bills extra credits whenever a rewrite is produced. Leave it off for latency-sensitive or cost-sensitive calls.193- `safe_mode: true` can blur otherwise valid inputs if the source image trips content classifiers; switch to `false` (and handle the legal/ToS consequences yourself) when you control the input.194- `/image/background-remove` takes **either** `image` **or** `image_url`, not both.