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"
}
{
"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']}")
第 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"
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
{
"model": "qwen-image-2",
"prompt": "A futuristic Venice skyline at sunrise",
"style_preset": "Cinematic"
}
请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|
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 信息；产生额外费用 |
模型专属选项
高分辨率生成
某些图像模型支持 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"
}
cfg_scale、style_preset、variants 或二进制响应）时，请使用 /image/generate。
Prompt 编写技巧
- 先写主体，然后添加媒介、灯光、构图和情绪。
- 把必须避免的细节放入
negative_prompt，而不是过载主 prompt。
- 迭代时重用
seed，以便在不完全改变构图的情况下比较 prompt 改动。
- 让尺寸感知模型。某些模型使用
width/height，某些使用 aspect_ratio，分辨率分级模型使用 aspect_ratio 加 resolution。
- 在探索阶段使用
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。
可用模型
请参阅图像模型了解当前模型列表、定价和功能支持。 
