venice-image-edit

Venice 图像编辑

四个端点，均用于处理现有图像：

端点	用途
POST /image/edit	使用文本提示词变换一张图像。支持 JSON 或 multipart/form-data。
POST /image/multi-edit	使用单个提示词合成／分层处理多张图像。支持 JSON 或 multipart/form-data。
POST /image/upscale	放大 2×–4×。支持 JSON 或 multipart/form-data。
POST /image/background-remove	生成透明 PNG 抠图。支持 JSON 或 multipart/form-data。

如需文生图，请参阅 venice-image-generate。

通用规则

	/image/edit	/image/multi-edit	/image/upscale	/image/background-remove
JSON 输入	image：原始 base64、data URI 或 http(s):// URL	images[]：原始 base64、data URI 或 http(s):// URL	image：仅原始 base64	image（base64 / data URI）或 image_url
Multipart 输入	image 中的一个文件	重复的 images 部分中的多个文件	image 中的一个文件	image 中的一个文件
最小尺寸	总计 ≥ 65,536 px，且每边 ≥ 64 px	同上	同上	Venice 不检查
最大尺寸	≤ 33,177,600 px（7680×4320）	同上	输出 ≤ 16,777,216 px（4096×4096）	Venice 不检查
响应	已编辑图像字节（PNG/JPEG/WebP）	已编辑图像字节	image/png	带 alpha 通道的 image/png
模型	model（默认值为 firered-image-edit）	modelId（默认值为 firered-image-edit）	固定：upscaler	固定：bria-bg-remover

• 支持的输入格式：JPEG、PNG、WebP、HEIF/HEIC、AVIF。不支持 SVG。背景移除端点不会预先验证格式，而是将图像直接传给模型。
• 文件必须小于 25 MB（超过 25 MB 的 multipart 文件会返回 413）。用于编辑和多图编辑的 URL 获取内容也限制为 25 MB。超过 35 MB 的 JSON 请求体（例如较大的 base64 图像）会返回 413。
• URL 由服务端获取，且必须可公开访问。私有、内部和元数据主机均会被屏蔽（400）。
• 这四个端点均以二进制形式返回图像，不会返回 JSON。没有 return_binary 字段（该标记仅存在于 /image/generate）。
• 编辑、多图编辑和背景移除端点的 JSON 请求体均为严格模式：未知字段会导致 400。/image/upscale 会忽略未知字段。
• 编辑、多图编辑和背景移除端点接受可选的 anon_user_id（可打印 ASCII 字符，≤ 128 个字符，不含 ||），用于上游终端用户归因。

选择编辑模型

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

对于每个模型，请查看 model_spec.constraints：

• aspectRatios[] — 允许的 aspect_ratio 值。并非每个模型都列出 auto（例如 gpt-image-2-edit、qwen-image-2-edit）；wan-2-7-pro-edit 只接受 auto。
• resolutions[] + defaultResolution — 当模型接受 resolution 时会提供。
• qualities[] + defaultQuality — 当模型接受 quality 时会提供（仅限多图编辑）。
• promptCharacterLimit — 各模型的限制（firered-image-edit 为 1,500，Nano Banana 编辑最高为 32,768）。
• combineImages — false 表示模型只接受一张输入图片。
• maxInputImages — 多图编辑的输入图片数量上限。若未设置此项且 combineImages 为 true，上限为 3。
• supportsOptimizePromptThinking — 表示 disable_prompt_optimization_thinking 是否生效。

定价：每次编辑的费用为 pricing.inpaint.usd；分级模型使用 pricing.resolutions[tier] / pricing.quality[tier][level]；按额外输入图片收费的模型使用 pricing.inputImages（包含 included + 每张额外图片的 additional.usd）。当 included 为 0 时（例如 qwen-image-3-edit、Grok Imagine 编辑模型），每张输入图片都会额外收费，包括 /image/edit 上的单张图片。

目前具有代表性的编辑 ID（列表经常变化，请从 /models 读取）：firered-image-edit（默认）、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（仅支持单张图片）。旧的 qwen-edit ID 仍可用作别名，并会运行 qwen-edit-uncensored。

/image/edit

使用简短、描述性的提示词编辑一张图片。

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 请求：将 image 作为文件部分发送，其他字段作为文本部分发送（-F [email protected] -F prompt=... -F model=...）。只允许发送一个文件。

字段	说明
model	默认值为 firered-image-edit。必须是 GET /models?type=inpaint 返回的 ID（否则返回 400 Invalid model id）。仍接受已弃用的别名 modelId；若两者均已发送，则以 model 为准。
prompt	必填。长度不得超过模型的 promptCharacterLimit（硬上限为 32,768）。提示词简短、具体效果最佳。
image	必填。请参阅关于可接受输入格式的通用规则。
aspect_ratio	可选：auto、1:1、3:2、16:9、21:9、9:16、2:3、3:4、4:3、4:5。必须在模型的 constraints.aspectRatios 中，否则返回 400。省略此字段（或在支持的情况下发送 auto）即可根据输入图片推断。
resolution	可选，例如 "1K"、"2K"、"4K"。必须在模型的 constraints.resolutions 中。向不支持分辨率的模型发送任何 resolution，此端点都会返回 400。 默认使用模型的 defaultResolution。
output_format	可选：jpeg（或 jpg）| png | webp。省略时：1K（或未指定分辨率）使用 PNG，2K/4K 使用 JPEG。
enhance_prompt	可选布尔值，默认值为 false。编辑前会根据输入图片改写提示词。最多增加约 30 秒耗时；若生成了改写结果，则收费 $0.04。改写后的提示词会以 URL 编码形式通过 x-venice-enhanced-prompt 响应头返回。
disable_prompt_optimization_thinking	可选布尔值。仅对 supportsOptimizePromptThinking: true 的模型生效；其他模型会忽略此字段。
safe_mode	默认值为 true；会模糊成人内容。

/image/edit 没有 quality 字段；发送该字段会返回 400，质量分级模型将按其 defaultQuality 计费。要选择质量档位（GPT Image 模型、ideogram-v4-5-edit），请使用 /image/multi-edit 并传入单张图片。

好的提示词示例：“移除这棵树”、“给这只猫戴上太阳镜”、“把天空变成鲜艳的橙色日出”。

/image/multi-edit

使用提示词将多张图片合并为一张。第一张图片是底图；其余图片是图层或参考图。至少需要 1 张图片。最大数量取决于模型：constraints.maxInputImages（当前大多数模型为 6）；如果该字段不存在，则为 3；当 combineImages 为 false 时，则为 1。

字段名称：/image/multi-edit 接受 modelId，而非 model。发送 model 会返回 400（未知字段）。

JSON（base64、数据 URI 或 URL）

{
  "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（文件上传）

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 中的 images 仅接受文件部分（不接受 URL 或 base64），且传输层最多允许 10 个文件。

字段	说明
modelId	默认值为 firered-image-edit。必须是修补模型 ID。
prompt	必填。长度不得超过模型的 promptCharacterLimit。
images	必填，数量为 1 到每个模型支持的最大值。对于 combineImages: false 的模型（例如 luma-uni-1-edit），传入多张图片会返回 400。
aspect_ratio	可选，与 /image/edit 使用相同的枚举值。必须是模型 aspectRatios 中的值。设为 auto 或省略时，会根据第一张图片推断。
resolution	可选。如果模型支持 resolutions，则必须是其中的值。对于不支持分辨率的模型，此参数会被静默丢弃（与 /image/edit 不同）。默认值为 defaultResolution。
quality	可选值为 low | medium | high，适用于支持 constraints.qualities 的模型（GPT Image 2 / 2.5 edits、ideogram-v4-5-edit；Grok Imagine 2.0 edit 接受 low/medium）。不在列表中的值会返回 400；其他模型会忽略此参数。省略时使用 defaultQuality。此参数会影响价格。
output_format	可选值为 jpeg/jpg | png | webp。省略时，1K 输出为 PNG，2K/4K 输出为 JPEG。
enhance_prompt	可选布尔值，默认值为 false。行为、$0.04 的费用以及 x-venice-enhanced-prompt 标头均与 /image/edit 相同。
disable_prompt_optimization_thinking	可选布尔值。
safe_mode	默认值为 true。

Edit / multi-edit 响应标头

标头	含义
Content-Type	根据输出字节检测（image/png、image/jpeg 或 image/webp）。
x-venice-model-id、x-venice-model-name	实际运行的模型。
x-venice-is-blurred	如果 safe_mode 对输出进行了模糊处理，则为 "true"。
x-venice-is-content-violation	状态码为 200 时始终为 "false"。被标记的编辑会返回 422（请参阅错误）。
x-venice-enhanced-prompt	经 URL 编码的改写提示词（仅当 enhance_prompt 生成了提示词时）。
x-venice-model-deprecation-warning、x-venice-model-deprecation-date、x-venice-deprecated、x-venice-deprecated-replacement	模型弃用相关提示。

/image/upscale

使用 Venice 的专用放大器（模型 ID upscaler）将图片放大 2×–4×。此接口接受三个字段。

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

字段	类型	默认值	说明
image	原始 base64 字符串（JSON）或文件（multipart 字段 image）	—	必填。不接受 URL。≥ 65,536 px 且 < 25 MB。
scale	数字，2–4	2	文档规定的值为 2 或 4。小于 2 的任何值（包括旧版 scale: 1）都会返回 400。如果 width × height × scale² 超过 16,777,216 px，系统会自动降低缩放比例。如果无法实现实际放大，则会返回 400。
creativity	数字	0.01	放大器增加细节和纹理的程度。取值限制在 0–0.02，因此 0.5 的效果与 0.02 相同。null 会被转换为 0。

响应：image/png 字节。每次成功放大都会收费。

计费（来自 /models 的 pricing.upscale）：有效缩放比例 ≤ 2 时为 $0.02，大于 2 时为 $0.08。例如，scale: 3 按 4× 费率计费。

**破坏性变更（放大器重写）：**旧版 enhance、enhanceCreativity、enhancePrompt 和 replication 字段不再起作用。这些字段会被静默忽略，不会被拒绝，因此请移除它们，以免造成混淆。creativity 并非重命名后的 enhanceCreativity：它的取值范围仅为 0–0.02，因此旧版 enhanceCreativity: 0.5 若作为 creativity: 0.5 发送，效果只会是 0.02（最大值）。

/image/background-remove

使用 bria-bg-remover（一种 anonymized 模型，每次调用收费 $0.03，见 /models）生成透明背景的 PNG 抠图。

# 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 [email protected]

• JSON：仅发送 image（非空的 base64；原始 base64 会按 PNG 处理）或 image_url 中的一个。两者都发送、都不发送，或 image 为空／仅含空白字符，都会返回 400。
• Multipart：在 image 中发送一个非空文件。Multipart 不接受 image_url。
• 响应：带 alpha 通道的 image/png，以及 x-venice-model-id / x-venice-model-name 标头。

错误行为（全部四个端点）

Code	Cause
400	参数错误：违反架构或包含未知字段、图像无效或损坏、图像太小、多重编辑图像超过 8K、未知或非编辑模型（Invalid model id）、提示词超过模型限制、模型不支持 aspect_ratio / resolution / quality、输入图像过多、URL 被拦截、不支持的 Content-Type（编辑、放大、背景移除）。
401	身份验证失败。
402	完全没有凭据（响应正文包含 x402 付款要求，且带有 PAYMENT-REQUIRED 标头）、余额不足（Bearer："Insufficient USD or Diem balance…"；x402 钱包：响应正文包含 PAYMENT_REQUIRED，且带有标头），或 API 密钥的 USD/DIEM 支出限额已达到。
403	API 密钥的 modelPrivacy 设置禁止使用该模型。PRIVATE_ONLY 密钥不能使用匿名模型，其中包括大多数编辑模型和 bria-bg-remover。
404	编辑 / 多重编辑：提供商无法找到或获取输入媒体（响应正文包含提供商的消息）。
413	Multipart 文件超过 25 MB，或请求正文过大。
415	仅限 /image/multi-edit，在请求正文为空时返回。任何路由上的 Content-Type 错误都会返回 400（"'Content-Type' must be 'application/json'"）——请发送 JSON 或 multipart。
422	编辑 / 多重编辑违反内容政策（{"error":"Your prompt violates the content policy of Venice.ai or the model provider"}，不含 code 字段），或图像在处理过程中超过像素限制（例如，/image/edit 输入超过 8K）。
429	请求被限流，或上游提供商过载。
500	编辑 / 放大 / 背景移除失败。
503	模型已达容量上限——使用抖动重试。

内容政策导致的 422 拒绝通常不会收费。如果 Venice 自身的审核在提供商已生成图像后拦截该图像，编辑会收费。有关响应正文格式和重试策略，请参阅 venice-errors。

注意事项

• 字段名称不一致：/image/edit 使用 model（modelId 是已弃用的别名）。/image/multi-edit 仅接受 modelId。
• resolution 在不同端点上的行为不同。在 /image/edit 上，向不支持分辨率的模型发送该字段会返回 400。在 /image/multi-edit 上，该字段会被静默丢弃。
• /image/multi-edit 支持 quality，但 /image/edit 不支持。
• 如果模型的 aspectRatios 不包含 "auto"（例如 gpt-image-2-edit），请勿发送 aspect_ratio: "auto"。应改为省略该字段。
• 对于 multipart /image/multi-edit，请发送多个字段名均为 images 的部分。顺序很重要：基础图像必须放在第一位。
• /image/upscale 的 JSON 中需要原始 base64。请去除任何 data:image/...;base64, 前缀。编辑、多重编辑和背景移除端点接受数据 URI。
• 对大型输入使用 /image/upscale 并设置 scale: 4 时，系统会静默降低放大比例，以确保不超过 16 MP；如果实际放大比例高于 2，仍会按 4× 费率计费。
• 在编辑 / 多重编辑中，如果 enhance_prompt 生成了改写内容，每次都会收取 $0.04。对延迟或成本敏感的调用，请将其关闭。
• safe_mode: true 可能会模糊原本有效的输出；请检查 x-venice-is-blurred。只有在你能控制输入并接受服务条款带来的后果时，才切换为 false。
• 某些模型会对超出包含数量的每张输入图像额外收费（pricing.inputImages）。如果 included 为 0，即使是单图 /image/edit 也会收取附加费。