Venice Image Editing

Four endpoints, all operating on existing images:

For text-to-image generation, see venice-image-generate.

Shared rules

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

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.

Edit / multi-edit response headers

/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
  }'

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)

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.