图像生成

使用 Venice 原生图像 API 或 OpenAI 兼容的 images 端点，从文本 prompt 生成图像，支持风格控制以及二进制或 base64 输出。

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

基于像素的尺寸示例：

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 步：解码并保存图像

Python

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 \
  -H "Authorization: Bearer $VENICE_API_KEY"

响应（200）：

[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]

然后将其中一个值传入您的生成请求：

{
  "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
style_preset	string	否	-	从图像风格应用预设风格
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 信息；产生额外费用

验证是模型专属的。在跨多个模型依赖某个参数之前，请查看图像模型和 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"
}

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

​

风格预设

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

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

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

---

​

OpenAI 兼容端点

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

请求：

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

使用 OpenAI 兼容路由可加快迁移。当您需要 Venice 专属选项（如 cfg_scale、style_preset、variants 或二进制响应）时，请使用 /image/generate。

---

​

Prompt 编写技巧

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

---

​

错误

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

启用 Safe Venice 时，如果您需要以编程方式检测审核结果，请检查响应头，例如 x-venice-is-blurred 和 x-venice-is-content-violation。

---

​

可用模型

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