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.

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

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.

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)

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

Multipart accepts only file parts for images (no URLs or base64), and at most 10 files at the transport layer.

| Field | Notes |
|---|---|
| modelId | Default firered-image-edit. Must be an inpaint model ID. |
| prompt | Required. ≤ the model's promptCharacterLimit. |
| images | Required, 1..per-model max. More than one image on a combineImages: false model (e.g. luma-uni-1-edit) is a 400. |
| aspect_ratio | Optional, same enum as /image/edit. Must be in the model's aspectRatios. auto or omitted infers it from the first image. |
| resolution | Optional. Must be in the model's resolutions if it has any. Silently dropped for models without resolutions (unlike /image/edit). Defaults to defaultResolution. |
| quality | Optional low \| medium \| high, for models with constraints.qualities (GPT Image 2 / 2.5 edits, ideogram-v4-5-edit; Grok Imagine 2.0 edit takes low/medium). A value outside the list is 400; ignored on other models. Omitted → defaultQuality. Changes the price. |
| output_format | Optional jpeg/jpg \| png \| webp. Omitted → PNG for 1K, JPEG for 2K/4K. |
| enhance_prompt | Optional bool, default false. Same behavior, $0.04 charge, and x-venice-enhanced-prompt header as /image/edit. |
| disable_prompt_optimization_thinking | Optional bool. |
| safe_mode | Default true. |

Edit / multi-edit response headers

| Header | Meaning |
|---|---|
| Content-Type | Detected from the output bytes (image/png, image/jpeg, or image/webp). |
| x-venice-model-id, x-venice-model-name | The model that ran. |
| x-venice-is-blurred | "true" if safe_mode blurred the output. |
| x-venice-is-content-violation | Always "false" on a 200. Flagged edits return 422 instead (see errors). |
| x-venice-enhanced-prompt | URL-encoded rewritten prompt (only when enhance_prompt produced one). |
| x-venice-model-deprecation-warning, x-venice-model-deprecation-date, x-venice-deprecated, x-venice-deprecated-replacement | Deprecation signals for the model. |

/image/upscale

Upscale 2×–4× with Venice's private upscaler (model ID upscaler). It takes three fields.

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 | raw base64 string (JSON) or file (multipart field image) | — | Required. URLs are not accepted. ≥ 65,536 px and < 25 MB. |
| scale | number, 2–4 | 2 | Documented as 2 or 4. Anything below 2 (including the old scale: 1) is a 400. If width × height × scale² would exceed 16,777,216 px, the scale is reduced automatically. If no real upscale fits, you get a 400. |
| creativity | number | 0.01 | How much detail and texture the upscaler adds. Clamped to 0–0.02, so 0.5 behaves as 0.02. null is coerced to 0. |

Response: image/png bytes. Every successful upscale is charged.

Billing (from /models pricing.upscale): $0.02 when the effective scale is ≤ 2, $0.08 when it is above 2. For example, scale: 3 bills at the 4× rate.

Breaking change (upscaler rewrite): the old enhance, enhanceCreativity, enhancePrompt, and replication fields no longer do anything. They are silently ignored, not rejected, so remove them to avoid confusion. creativity is not enhanceCreativity renamed: its range is only 0–0.02, so an old enhanceCreativity: 0.5 sent as creativity: 0.5 just behaves as 0.02 (the max).

/image/background-remove

Produce a transparent PNG cutout with bria-bg-remover (an anonymized model, $0.03 per call per /models).

# With base64 (raw or data URI)
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"}'

# With a file
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F image=@photo.jpg

• JSON: send exactly one of image (non-empty base64; raw base64 is treated as PNG) or image_url. Sending both, neither, or an empty/whitespace image is a 400.
• Multipart: one non-empty file in image. image_url is not accepted in multipart.
• Response: image/png with alpha, plus x-venice-model-id / x-venice-model-name headers.

Error behavior (all four endpoints)

| Code | Cause |
|---|---|
| 400 | Bad params: schema violation or unknown field, invalid or corrupt image, image too small, multi-edit image over 8K, unknown/non-edit model (Invalid model id), prompt over the model limit, aspect_ratio/resolution/quality not supported by the model, too many input images, blocked URL, unsupported Content-Type (edit, upscale, background-remove). |
| 401 | Auth failed. |
| 402 | No credentials at all (x402 payment-requirements body + PAYMENT-REQUIRED header), insufficient balance (Bearer: "Insufficient USD or Diem balance…"; x402 wallet: PAYMENT_REQUIRED body + header), or the API key's USD/DIEM spend limit is reached. |
| 403 | The API key's modelPrivacy setting blocks the model. A PRIVATE_ONLY key can't use anonymized models, which includes most edit models and bria-bg-remover. |
| 404 | Edit / multi-edit: the provider couldn't find or fetch the input media (the body carries the provider's message). |
| 413 | Multipart file over 25 MB, or request body too large. |
| 415 | /image/multi-edit only, when the body is empty. A wrong Content-Type on any route is a 400 ("'Content-Type' must be 'application/json'") — send JSON or multipart. |
| 422 | Content-policy violation on edit / multi-edit ({"error":"Your prompt violates the content policy of Venice.ai or the model provider"}, no code field), or an image exceeds a pixel limit during processing (e.g. an /image/edit input over 8K). |
| 429 | Rate limited, or the upstream provider is overloaded. |
| 500 | Edit / upscale / background removal failed. |
| 503 | Model at capacity — retry with jitter. |

A 422 content-policy rejection is normally not charged. If Venice's own moderation blocks an image after the provider already generated it, the edit is charged. See venice-errors for body shapes and retry strategy.

Gotchas

• Field-name asymmetry: /image/edit uses model (modelId is a deprecated alias). /image/multi-edit accepts only modelId.
• resolution behaves differently per endpoint. On /image/edit, sending it to a model without resolutions is a 400. On /image/multi-edit, it is silently dropped.
• quality exists on /image/multi-edit but not on /image/edit.
• Don't send aspect_ratio: "auto" to a model whose aspectRatios don't include it (e.g. gpt-image-2-edit). Omit the field instead.
• For multipart /image/multi-edit, send multiple parts with the same field name images. Order matters: the base image goes first.
• /image/upscale needs raw base64 in JSON. Strip any data:image/...;base64, prefix. Edit, multi-edit, and background-remove accept data URIs.
• /image/upscale with scale: 4 on a large input is silently reduced to stay under 16 MP, and it still bills at the 4× rate if the effective scale is above 2.
• enhance_prompt on edit / multi-edit bills $0.04 whenever a rewrite is produced. Leave it off for latency- or cost-sensitive calls.
• safe_mode: true can blur otherwise valid outputs; check x-venice-is-blurred. Switch to false only when you control the input and accept the ToS consequences.
• Some models charge extra for each input image beyond the included count (pricing.inputImages). Where included is 0, even a single-image /image/edit pays the surcharge.