Prompt Enhancement | Venice API Docs

Prompt 增强会在图像生成或编辑之前重写您的 prompt，补充清晰的视觉细节，把简短或稀疏的描述扩展为更丰富的 prompt，让图像模型更可靠地按其执行。在 POST /image/generate、POST /image/edit 或 POST /image/multi-edit 上设置 enhance_prompt: true 即可启用。对于图像生成，这与 Venice web 应用中”魔法棒”背后的增强功能相同。对于图像编辑，则会使用带视觉理解能力的增强器，根据输入的一张或多张图像来澄清您的编辑指令。

何时使用

Prompt 增强在以下场景中最有用：

您的 prompt 很短（几个词或单个短语），并且希望模型自行补充构图、光照和氛围。
您正在构建的产品中，终端用户输入的是随意的 prompt，可以从扩展中受益。
您正在编辑一张图像，并希望指令能结合可见内容进行改写。
您希望在不手动撰写长 prompt 的情况下获得更一致、更详细的输出。

如果您已经发送经过精心撰写的长 prompt，通常关闭增强会得到更好的控制。

第 1 步：发送启用增强的请求

在任何标准图像生成请求中添加 enhance_prompt: true。

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "format": "webp"
  }'

Venice 会将 "a cabin in the woods" 重写为更详细的 prompt，然后使用重写后的文本进行生成。请求的其余行为与普通生成调用完全相同。

增强会在生成开始前额外增加最多约 30 秒，因为重写是由一次单独的模型调用产生的。请在客户端超时中考虑到这一点。

第 2 步：从响应头中读取增强后的 prompt

当发生重写时，Venice 会将最终 prompt 以 URL 编码形式通过 x-venice-enhanced-prompt 响应头返回。解码后即可查看、记录或展示实际发送给图像模型的内容。

import base64
import os
from urllib.parse import unquote

import requests

response = requests.post(
    "https://api.venice.ai/api/v1/image/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "venice-sd35",
        "prompt": "a cabin in the woods",
        "enhance_prompt": True,
        "format": "webp",
    },
)

data = response.json()

enhanced = response.headers.get("x-venice-enhanced-prompt")
if enhanced:
    print("Enhanced prompt:", unquote(enhanced))
else:
    print("No enhancement was applied; original prompt was used.")

image_bytes = base64.b64decode(data["images"][0])
with open("output.webp", "wb") as f:
    f.write(image_bytes)

import fs from "fs";

const response = await fetch("https://api.venice.ai/api/v1/image/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "venice-sd35",
    prompt: "a cabin in the woods",
    enhance_prompt: true,
    format: "webp",
  }),
});

const data = await response.json();

const enhanced = response.headers.get("x-venice-enhanced-prompt");
if (enhanced) {
  console.log("Enhanced prompt:", decodeURIComponent(enhanced));
} else {
  console.log("No enhancement was applied; original prompt was used.");
}

const imageBuffer = Buffer.from(data.images[0], "base64");
fs.writeFileSync("output.webp", imageBuffer);

只有当实际生成并应用了重写时，才会出现 x-venice-enhanced-prompt 响应头。如果增强被跳过或失败，则不会出现该响应头，并使用您的原始 prompt。

在图像编辑中使用增强

编辑端点使用带视觉理解能力的增强器，会在重写指令之前分析输入的一张或多张图像。这有助于把 "make it winter" 这样简短的请求转化为更具体的编辑，同时保留相关主体和构图。对于单图像编辑，可以在 JSON 或 multipart 请求中包含 enhance_prompt：

curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "image": "https://example.com/cabin.jpg",
    "prompt": "make it winter",
    "enhance_prompt": true
  }'

对于 multi-edit，请对 images 数组使用同一参数：

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "images": [
      "https://example.com/cabin.jpg",
      "https://example.com/snow-reference.jpg"
    ],
    "prompt": "make the first image match this winter atmosphere",
    "enhance_prompt": true
  }'

两个编辑端点都会以二进制数据返回编辑后的图像。与生成一样，可以查看并对 x-venice-enhanced-prompt 进行 URL 解码，以查看已应用的重写内容。

行为

方面	行为
支持的端点	`POST /image/generate`、`POST /image/edit` 和 `POST /image/multi-edit`
默认值	`enhance_prompt` 默认为 `false`；除非您显式开启，否则不会进行增强。
失败宽容	如果重写因任何原因失败，生成或编辑会继续使用您的原始 prompt。请求不会因为增强而报错。
图像感知的编辑	在编辑请求中，增强器会在重写指令时分析所提供的一张或多张图像。
字符长度限制	对于生成，增强后的 prompt 会被截断至所选模型的 `promptCharacterLimit`（参见 Models API）。
安全模式	对于生成请求，增强过程会遵循 `safe_mode`。当 `safe_mode: true` 时，重写内容会保持 SFW。
响应头	当应用增强时，最终 prompt 会以 URL 编码形式通过 `x-venice-enhanced-prompt` 返回。

定价

Prompt 增强按每次成功应用的重写 $0.04 的固定附加费计费，叠加在正常的图像生成费用之上。计费规则：

仅当实际生成并应用了重写时才会计费。如果增强被跳过或失败回退到您的原始 prompt，则不收取附加费。
附加费在图像成功路径上计费。如果生成以内容违规结束，则不收取增强费用。
当您使用 variants 请求多张图像时，共享的重写在每个请求中最多计费一次，而非按每个 variant 计费。

图像生成的基础费用请参见定价。

将增强与 variants 一起使用

在探索创意时，增强与 variants 搭配效果很好：生成一次重写，然后在所有 variant 之间复用，这样您只需支付一次 $0.04 附加费。

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "variants": 4
  }'

variants 仅在 return_binary 为 false 时受支持。详情参见图像生成。

Prompt 技巧

让您的输入 prompt 专注于主体和任何不可协商的细节。增强会围绕它补充风格、光照和构图。
在开发阶段记录 x-venice-enhanced-prompt 响应头，以便了解增强添加了哪些内容，并决定何时更愿意手工撰写 prompt。
为了在一批生成中获得可复用的结果，先启用增强生成一次，从响应头中捕获增强后的 prompt，然后关闭 enhance_prompt 复用该确切文本。
对于图像生成，将捕获的 prompt 与固定的 seed 结合，可以在不再次重写的情况下比较其他参数变更。

错误

增强本身失败宽容，不会抛出自身的错误码。标准的图像生成错误仍然适用。

状态	含义	应对方式
`400`	请求参数无效	检查字段名、类型和模型专属约束
`401`	身份验证失败或模型需要更高访问级别	检查您的 API 密钥和模型访问权限
`402`	余额不足	在 venice.ai/settings/api 充值
`429`	速率限制超出或模型过载	使用退避重试；查看 `Retry-After` 响应头
`500`	推理处理失败	重试请求
`503`	模型容量已满	短暂延迟后重试

详情请参见完整的错误码参考。

文档

快速开始

文本与聊天

图像、视频与音频

智能体与集成

编程工具

智能体工具

SDK 与框架

Prompt 增强

何时使用

第 1 步：发送启用增强的请求

第 2 步：从响应头中读取增强后的 prompt

在图像编辑中使用增强

行为

定价

将增强与 variants 一起使用

Prompt 技巧

错误

相关内容

​何时使用

​第 1 步：发送启用增强的请求

​第 2 步：从响应头中读取增强后的 prompt

​在图像编辑中使用增强

​行为

​定价

​将增强与 variants 一起使用

​Prompt 技巧

​错误

​相关内容

何时使用

第 1 步：发送启用增强的请求

第 2 步：从响应头中读取增强后的 prompt

在图像编辑中使用增强

行为

定价

将增强与 variants 一起使用

Prompt 技巧

错误

相关内容