> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt 增强

> 使用 Venice 的 enhance_prompt 参数自动重写图像生成和编辑的 prompt，补充更清晰的视觉细节并提升输出质量。

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`。

```bash theme={"system"}
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，然后使用重写后的文本进行生成。请求的其余行为与普通生成调用完全相同。

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

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

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

<CodeGroup>
  ```python Python theme={"system"}
  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)
  ```

  ```javascript Node.js theme={"system"}
  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);
  ```
</CodeGroup>

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

## 在图像编辑中使用增强

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

对于单图像编辑，可以在 JSON 或 multipart 请求中包含 `enhance_prompt`：

```bash theme={"system"}
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` 数组使用同一参数：

```bash theme={"system"}
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](/api-reference/endpoint/models/list)）。 |
| 安全模式    | 对于生成请求，增强过程会遵循 `safe_mode`。当 `safe_mode: true` 时，重写内容会保持 SFW。                                             |
| 响应头     | 当应用增强时，最终 prompt 会以 URL 编码形式通过 `x-venice-enhanced-prompt` 返回。                                             |

## 定价

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

计费规则：

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

图像生成的基础费用请参见[定价](/overview/pricing)。

## 将增强与 variants 一起使用

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

```bash theme={"system"}
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
  }'
```

<Note>
  `variants` 仅在 `return_binary` 为 `false` 时受支持。详情参见[图像生成](/guides/media/image-generation)。
</Note>

## Prompt 技巧

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

## 错误

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

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

详情请参见完整的[错误码](/api-reference/error-codes)参考。

## 相关内容

* [图像生成](/guides/media/image-generation) — 完整的生成指南，包括尺寸、风格和二进制响应。
* [图像编辑](/guides/media/image-editing) — 单图像编辑、分层 multi-edit 请求和二进制响应。
* [生成图像（API 参考）](/api-reference/endpoint/image/generate) — `POST /image/generate` 的每个请求和响应字段。
* [编辑图像（API 参考）](/api-reference/endpoint/image/edit) — `POST /image/edit` 的请求字段。
* [多图像编辑（API 参考）](/api-reference/endpoint/image/multi-edit) — `POST /image/multi-edit` 的请求字段。
* [图像模型](/models/image) — 模型列表、定价及每个模型的 `promptCharacterLimit`。