Image Generation | Venice API Docs

Venice 上的图像生成是同步的。将 prompt 发送到 /image/generate，并在同一响应中收到您的图像，可以是 JSON 中的 base64，或在 return_binary 为 true 时为原始二进制。

端点

端点	用途	何时使用
`POST /image/generate`	Venice 原生图像生成 API	用于完整功能支持
`GET /image/styles`	列出可用的风格预设	在发送 `style_preset` 之前使用
`POST /images/generations`	OpenAI 兼容的图像生成 API	迁移现有 OpenAI 图像客户端时使用

第 1 步：发送生成请求

尺寸是模型专属的。某些模型接受显式的 width 和 height；某些公开 aspect_ratio；分辨率分级模型公开 aspect_ratio 加上 resolution 值（如 1K、2K 或 4K）。

qwen-image、qwen-image-3、qwen-image-3-pro、qwen-image-2-1-turbo 和 qwen-image-2-1-pro 不再接受 width 或 height。发送任一参数都会返回 400 及 “width and height are no longer supported for this model. Use aspect_ratio instead.” 在选择尺寸字段之前，请先通过 GET /models?type=image 检查 model_spec.constraints。

基于像素的尺寸示例：

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "venice-sd35",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
  "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

基于宽高比的尺寸示例：

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-image-2",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "format": "webp"
}

基于分辨率等级的尺寸示例：

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "format": "png"
}

相同模式也适用于其他分辨率分级模型：

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

使用图像模型或 Models API 确认每个模型接受哪些尺寸字段。 响应（200）：

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

images 数组包含 base64 编码的图像数据。解码第一项以保存或显示。timing.total 是完整的请求时长（毫秒）。

第 2 步：解码并保存图像

import base64
import os
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 cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
        "width": 1024,
        "height": 1024,
        "format": "webp",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0])

with open("output.webp", "wb") as f:
    f.write(image_bytes)

print(f"Saved image from request {data['id']}")

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 cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
    width: 1024,
    height: 1024,
    format: "webp",
  }),
});

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

console.log(`Saved image from request ${data.id}`);

第 3 步：返回二进制而非 JSON（可选）

如果您希望响应体本身就是图像文件，请设置 return_binary: true。当您希望直接流式传输或保存图像而不进行 base64 解码时，这非常有用。

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.png \
  -d '{
    "model": "qwen-image-2",
    "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones",
    "format": "png",
    "return_binary": true
  }'

当 return_binary 为 true 时，响应体根据您请求的 format 是原始 image/jpeg、image/png 或 image/webp 数据。

仅当 return_binary 为 false 时才支持 variants。

第 4 步：列出可用图像风格（可选）

如果您想使用 style_preset，请先从 /image/styles 获取可用风格：

curl https://api.venice.ai/api/v1/image/styles

此端点是公开的，无需 API 密钥。 响应（200）：

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

样式名称位于 data 内部，而不在顶层——请读取 response.data，而不是直接迭代响应对象。然后将其中一个值传入您的生成请求：

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

当您想要确切的预设名称而非猜测时，请使用 styles 端点。

请求参数

参数	类型	必填	默认	说明
`model`	string	是	-	用于生成的模型 ID
`prompt`	string	是	-	要生成的内容
`negative_prompt`	string	否	-	在图像中要避免的内容
`width`	integer	否	`1024`	基于像素的模型（如 `venice-sd35`）的输出宽度（像素）。会被 Qwen Image 系列拒绝——见下方说明
`height`	integer	否	`1024`	基于像素的模型（如 `venice-sd35`）的输出高度（像素）。会被 Qwen Image 系列拒绝——见下方说明
`format`	string	否	`webp`	输出格式：`jpeg`、`png` 或 `webp`
`variants`	integer	否	`1`	要生成的图像数（`1`-`4`），仅当 `return_binary` 为 `false` 时。提供商明确的内容政策拒绝可能会省略个别变体；请参阅部分变体结果
`return_binary`	boolean	否	`false`	返回原始图像字节而非 base64 JSON
`safe_mode`	boolean	否	`true`	启用时模糊成人内容
`seed`	integer	否	随机	重用相同 seed 以实现更一致的迭代
`cfg_scale`	number	否	模型相关	较高值推动模型更紧密地遵循 prompt
`lora_strength`	integer	否	-	模型所用附加 LoRA 的强度（`0`-`100`）。参见 LoRA 强度
`style_preset`	string	否	-	从图像风格应用预设风格
`style_references`	array	否	-	用于引导输出美学风格的风格参考图像。每个条目为 `{ "image": <url or base64>, "strength": <0.1-1> }`。仅限支持的模型；请参阅风格参考
`aspect_ratio`	string	条件	-	由支持基于比例尺寸的模型使用，例如 `qwen-image-2`、`gpt-image-2`、`nano-banana-2` 和 `nano-banana-pro`
`resolution`	string	条件	-	由支持分辨率分级（如 `1K`、`2K` 或 `4K`）的模型使用
`enable_web_search`	boolean	条件	`false`	允许支持的模型使用当前 web 信息；产生额外费用
`transparent_background`	boolean	否	`false`	返回带真实 alpha 通道的 PNG 或 WebP。需要使用 `supportsTransparentBackground: true` 的模型，且 `format` 为 `png` 或 `webp`。请参见透明背景图像

验证是模型专属的。在跨多个模型依赖某个参数之前，请查看图像模型和 Models API。

模型专属选项

高分辨率生成

某些图像模型支持 aspect_ratio 但没有可选的 resolution 等级。例如，qwen-image-2 接受宽高比并映射到模型专属的输出尺寸：

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

其他图像模型支持 aspect_ratio 加上 resolution 等级。例如，gpt-image-2、nano-banana-2 和 nano-banana-pro 支持 1K、2K 和 4K：

{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

使用图像模型查看哪些模型支持更高分辨率及其定价。

LoRA 强度

部分图像模型会应用附加 LoRA。lora_strength（integer，0 到 100）用于设置其应用强度，且仅对使用 LoRA 的模型生效。 API 不接受自定义 LoRA 文件，也没有端点可以列出模型所用的 LoRA。lora_strength 是唯一的 LoRA 控制项。

成人内容与安全模式

safe_mode 控制生成输出中的成人内容是否被模糊处理。默认为 true，因此被分类为成人内容的图像会以模糊形式返回，除非您发送 safe_mode: false：

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

所有 API 用户都可以获取未模糊处理的成人（NSFW）图像。您无需 Pro 订阅，并且 Venice 应用中的成人内容过滤设置不会影响通过 API 发出的图像请求。某些图像模型专为成人 / 无审查生成而设计，与 safe_mode: false 搭配效果良好。定价页面上的示例包括 lustify-sdxl、lustify-v7 和 lustify-v8。请参阅图像模型和定价获取当前列表和各模型的费用。对于编辑现有图像，默认的编辑模型是 firered-image-edit。内容政策因编辑模型而异；如果您需要无审查编辑，请通过图像编辑使用 qwen-edit-uncensored。启用 safe_mode 且模型返回模糊或经过审核的输出时，如果您需要以编程方式检测，请检查响应头 x-venice-is-blurred 和 x-venice-is-content-violation。

正在使用第三方应用？除非该应用发送 safe_mode: false，或在 OpenAI 兼容端点上发送 moderation: "low"（见下文），否则成人图像将保持模糊。

风格预设

如果所选模型支持，style_preset 让您可以在不重写整个 prompt 的情况下引导输出。您可以从图像风格获取有效的预设名称：

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

当前风格列表请参阅图像风格。

风格参考

style_references 比 style_preset 更进一步：它不使用命名预设，而是以一张或多张参考图像作为生成条件。每个条目包含 image 和可选的 strength：

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

字段	类型	必填	说明
`image`	string	是	参考图像，可以是 `http://` 或 `https://` URL、base64 字符串或 base64 data URI。必须是栅格图像（JPEG、PNG、WebP、HEIF、HEIC 或 AVIF），不能是 SVG，且必须小于 8 MB
`strength`	number	否	参考图像对输出的引导强度，范围为 `0.1` 到 `1`。默认为 `0.5`。对于 `supportsStyleReferenceStrength` 为 `false` 的模型会被忽略

是否支持因模型而异。请查看 GET /models?type=image：

仅在接受该字段的模型上，model_spec.supportsStyleReferences 为 true。
model_spec.constraints.maxStyleReferences 是该模型可接受的条目数量。
model_spec.constraints.supportsStyleReferenceStrength 表示 strength 是否有效。

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

向不支持的模型发送 style_references 会返回 400；超出该模型的数量上限，或发送损坏、无法访问或过大的参考图像，也会返回 400。某些模型会在基础图像价格之上，对每张返回的图像额外收取风格参考费用，例如 Krea v2 Large 和 Krea v2 Medium。该费用仅针对实际返回的图像收取。基础单张图像价格请参阅图像模型。

部分变体结果

当 variants 大于 1 时，个别变体可能会被提供商的内容政策拒绝，而其余变体生成成功。在这种情况下，端点仍会返回 200，但图像数量少于您请求的数量：

当有一个或多个变体被省略时，JSON 响应体会包含 content_policy_violation_count，即被省略的变体数量。
x-venice-content-violation-count 响应头携带相同的计数。
x-venice-is-content-violation 和 x-venice-is-blurred 描述的是实际返回的图像。

如果所有请求的变体都被拒绝，则不会返回任何图像，请求将改为以 422 失败。不要假设 len(images) == variants；请将数组长度与 variants 进行比较，并在存在时检查 content_policy_violation_count。

OpenAI 兼容端点

如果您已在使用 OpenAI 图像 SDK 或现有的 DALL-E 集成，Venice 也支持 POST /images/generations。它提供更简单的请求格式，但功能比 Venice 原生端点少。 请求：

{
  "model": "z-image-turbo",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

size 仅适用于按像素尺寸设置的模型，即在 GET /models?type=image 返回的 model_spec.constraints 中 widthHeightDivisor 大于 1 的模型。大多数模型（包括 qwen-image-2）改为按宽高比和分辨率设置输出尺寸，并会忽略 size。为兼容 SDK，部分 OpenAI 参数会被接受但被忽略（n 仅限为 1）：

参数	在 `/images/generations` 上的行为
`quality`	接受但忽略。计费使用模型的默认质量等级
`style`	接受但忽略
`output_compression`	接受但忽略
`user`	接受后丢弃，且不是 `anon_user_id` 的别名
`n`	仅支持 `1`；其他值会被验证拒绝

此路由不提供等级控制：没有 resolution 或 aspect_ratio 字段，quality 也无法提高或降低费用。对于分级的 GPT Image 模型，当您需要选择 quality、resolution 或 aspect_ratio 时，请使用原生 /image/generate 端点。使用 OpenAI 兼容路由可加快迁移。当您需要 Venice 专属选项（如 cfg_scale、style_preset、style_references、variants 或二进制响应）时，请使用 /image/generate。

在 `/images/generations` 上控制成人内容模糊

OpenAI 兼容端点不接受 safe_mode。发送该参数会返回 400 及 Unrecognized key(s) in object: 'safe_mode'。请改用 OpenAI 风格的 moderation 参数：

值	行为
`auto`（默认）	模糊成人内容，等同于 `safe_mode: true`
`low`	返回未模糊输出，等同于 `safe_mode: false`

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode 仅在原生 POST /image/generate 端点上有效。moderation 仅在 OpenAI 兼容的 POST /images/generations 端点上有效。透明度也遵循同样的区分：/image/generate 使用 transparent_background: true，而 /images/generations 使用 OpenAI 风格的 background: "transparent"。两者都要求 png 或 webp 输出格式，以及 supportsTransparentBackground: true 的模型。请参见透明背景图像。

Prompt 编写技巧

先写主体，然后添加媒介、灯光、构图和情绪。
把必须避免的细节放入 negative_prompt，而不是过载主 prompt。
迭代时重用 seed，以便在不完全改变构图的情况下比较 prompt 改动。
让尺寸感知模型。某些模型使用 width/height，某些使用 aspect_ratio，分辨率分级模型使用 aspect_ratio 加 resolution。
在探索阶段使用 variants，方向锁定后切回单一输出。

错误

状态	含义	应对方式
`400`	请求参数无效	检查字段名、类型和模型专属约束
`401`	身份验证失败，或模型需要更高访问等级	检查 API 密钥和模型访问权限
`402`	余额不足	在 venice.ai/settings/api 充值
`404`	未知模型	对照 `GET /models?type=image` 检查模型 ID
`415`	内容类型无效	使用 `Content-Type: application/json` 发送 JSON
`422`	内容政策违规	提供商明确拒绝了该 prompt 或图像。请调整 prompt 或更换模型。响应体包含 `error` 和布尔值 `retryable`，还可能包含 `suggested_prompt` 和 `recommended_model`
`429`	速率限制超出或模型过载	使用退避重试；查看 `Retry-After` 请求头
`500`	推理处理失败	重试请求
`503`	模型容量已满	短暂延迟后重试

启用 safe_mode（或 moderation 为 auto）时，如果您需要以编程方式检测审核结果，请检查响应头，例如 x-venice-is-blurred 和 x-venice-is-content-violation。

可用模型

请参阅图像模型了解当前模型列表、定价和功能支持。

文档

快速开始

文本与聊天

图像

视频

音频

搜索与 RAG

智能体与集成

编程工具

智能体工具

SDK 与框架

图像生成

端点

第 1 步：发送生成请求

第 2 步：解码并保存图像

第 3 步：返回二进制而非 JSON（可选）

第 4 步：列出可用图像风格（可选）

请求参数

模型专属选项

高分辨率生成

LoRA 强度

成人内容与安全模式

风格预设

风格参考

部分变体结果

OpenAI 兼容端点

在 `/images/generations` 上控制成人内容模糊

Prompt 编写技巧

错误

可用模型

​端点

​第 1 步：发送生成请求

​第 2 步：解码并保存图像

​第 3 步：返回二进制而非 JSON（可选）

​第 4 步：列出可用图像风格（可选）

​请求参数

​模型专属选项

​高分辨率生成

​LoRA 强度

​成人内容与安全模式

​风格预设

​风格参考

​部分变体结果

​OpenAI 兼容端点

​在 /images/generations 上控制成人内容模糊

​Prompt 编写技巧

​错误

​可用模型

端点

第 1 步：发送生成请求

第 2 步：解码并保存图像

第 3 步：返回二进制而非 JSON（可选）

第 4 步：列出可用图像风格（可选）

请求参数

模型专属选项

高分辨率生成

LoRA 强度

成人内容与安全模式

风格预设

风格参考

部分变体结果

OpenAI 兼容端点

在 `/images/generations` 上控制成人内容模糊

Prompt 编写技巧

错误

可用模型