Back to Details

venice-image-generate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Venice Image Generation

Venice 图像生成

Two text-to-image endpoints:
  1. POST /api/v1/image/generate
     — Venice-native, full control (negative prompts, CFG, seed, up to 4 variants).
  2. POST /api/v1/images/generations
     — OpenAI-compatible, fewer knobs but drop-in for the OpenAI SDK.
Plus:
  • GET /api/v1/image/styles
     — list of style preset names for 
    style_preset
    .
For editing / upscaling / multi-image / background removal, see 
venice-image-edit
.
两个文本转图像接口：
  1. POST /api/v1/image/generate
     — Venice原生接口，支持完全控制（负提示词、CFG、种子值、最多4个变体图像）。
  2. POST /api/v1/images/generations
     — 兼容OpenAI接口，可调节参数较少，但可直接替换OpenAI SDK使用。
额外接口：
  • GET /api/v1/image/styles
     — 获取可用于
    style_preset
    的风格预设名称列表。
如需编辑/超分辨率/多图像处理/背景移除功能，请查看
venice-image-edit
。

Use when

适用场景

  • You need to generate images from text prompts.
  • You need multiple variants in one call.
  • You're porting from OpenAI's 
    images.generate
    and want a zero-change SDK swap.
  • You want to browse style presets before committing to one.
  • 你需要通过文本提示生成图像。
  • 你需要在一次调用中生成多个变体图像。
  • 你正在迁移OpenAI的
    images.generate
    功能，希望实现SDK零改动替换。
  • 你想在确定使用某一风格前浏览所有风格预设。

/image/generate
— Venice-native

/image/generate
— Venice原生接口

Request

请求示例

bash
curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A beautiful sunset over a mountain range",
    "width": 1024,
    "height": 1024,
    "cfg_scale": 7.5,
    "steps": 8,
    "seed": 123456789,
    "variants": 1,
    "format": "webp",
    "style_preset": "3D Model",
    "safe_mode": true
  }'
bash
curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A beautiful sunset over a mountain range",
    "width": 1024,
    "height": 1024,
    "cfg_scale": 7.5,
    "steps": 8,
    "seed": 123456789,
    "variants": 1,
    "format": "webp",
    "style_preset": "3D Model",
    "safe_mode": true
  }'

Fields

请求字段

FieldTypeDefaultNotes
model
string—Required. Image model ID. 
GET /models?type=image
.
prompt
string—Required. Max 
promptCharacterLimit
from the model's 
model_spec.constraints
(typically 1500–7500).
negative_prompt
string—Describe what not to show. Same character cap as prompt.
width
, 
height
int1024, 1024≤ 1280 each. Must be divisible by 
constraints.widthHeightDivisor
on the model's 
model_spec
.
aspect_ratio
string—
"1:1"
, 
"16:9"
, 
"9:16"
, … — used by models like Nano Banana instead of width/height.
resolution
string—
"1K"
, 
"2K"
, 
"4K"
— used by resolution-driven models.
cfg_scale
numbermodel default0 < x ≤ 20. Higher = more prompt adherence.
steps
int8Inference steps. Some models ignore it (e.g. Turbo).
seed
int0
-999999999..999999999
. Use 
0
/omit for random.
variants
int11–4. Only if 
return_binary: false
.
lora_strength
int—0–100 when model uses Loras.
style_preset
string—Value from 
GET /image/styles
.
format
"webp"
/
"png"
/
"jpeg"
webp
Response image format.
return_binary
bool
false
true
→ binary 
image/*
response; 
false
→ JSON with base64.
embed_exif_metadata
bool
false
Embed prompt info in EXIF.
hide_watermark
bool
false
Venice may still watermark certain content.
safe_mode
bool
true
Blurs adult content.
enable_web_search
bool
false
Only some models. Charges extra.
inpaint
——Deprecated since May 19 2025. A new inpaint API is forthcoming.
字段类型默认值说明
model
string—必填项。图像模型ID。可通过
GET /models?type=image
获取。
prompt
string—必填项。最大长度由模型
model_spec.constraints
中的
promptCharacterLimit
决定（通常为1500–7500）。
negative_prompt
string—描述不需要出现在图像中的内容。长度限制与
prompt
相同。
width
, 
height
int1024, 1024各自最大值≤1280。必须能被模型
model_spec
中的
constraints.widthHeightDivisor
整除。
aspect_ratio
string—
"1:1"
, 
"16:9"
, 
"9:16"
等 — 适用于Nano Banana这类模型，替代width/height参数。
resolution
string—
"1K"
, 
"2K"
, 
"4K"
— 适用于按分辨率驱动的模型。
cfg_scale
number模型默认值0 < x ≤ 20。数值越高，图像与提示词的贴合度越高。
steps
int8推理步数。部分模型会忽略该参数（如Turbo系列）。
seed
int0取值范围
-999999999..999999999
。设为
0
或省略时使用随机值。
variants
int1取值范围1–4。仅当
return_binary: false
时生效。
lora_strength
int—当模型使用Loras时，取值范围0–100。
style_preset
string—值来自
GET /image/styles
接口的返回结果。
format
"webp"
/
"png"
/
"jpeg"
webp
响应图像的格式。
return_binary
bool
false
true
→ 返回二进制
image/*
格式响应；
false
→ 返回包含base64编码的JSON响应。
embed_exif_metadata
bool
false
在EXIF中嵌入提示词信息。
hide_watermark
bool
false
对于特定内容，Venice仍可能添加水印。
safe_mode
bool
true
对成人内容进行模糊处理。
enable_web_search
bool
false
仅部分模型支持。会额外收费。
inpaint
——已废弃（自2025年5月19日起）。新的inpaint API即将推出。

Response (JSON, 
return_binary: false
)

响应示例（JSON格式，
return_binary: false
）

json
{
  "id": "...",
  "images": ["<base64>", "<base64>"],
  "timing": {...},
  "request": {...}
}
With 
return_binary: true
, response is raw 
image/webp
(or 
png
/
jpeg
) with matching 
Content-Type
.
json
{
  "id": "...",
  "images": ["<base64>", "<base64>"],
  "timing": {...},
  "request": {...}
}
当
return_binary: true
时，响应为原始
image/webp
（或
png
/
jpeg
）格式，同时匹配对应的
Content-Type
头。

/images/generations
— OpenAI-compatible

/images/generations
— 兼容OpenAI接口

Use this if you're already on the OpenAI SDK. Field names match 
openai.images.generate()
.
ts
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const res = await client.images.generate({
  model: 'z-image-turbo',
  prompt: 'A beautiful sunset over mountain ranges',
  size: '1024x1024',
  response_format: 'b64_json',
})

const b64 = res.data[0].b64_json
如果你已在使用OpenAI SDK，可使用此接口。字段名称与
openai.images.generate()
完全匹配。
ts
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const res = await client.images.generate({
  model: 'z-image-turbo',
  prompt: 'A beautiful sunset over mountain ranges',
  size: '1024x1024',
  response_format: 'b64_json',
})

const b64 = res.data[0].b64_json

Mapped fields

字段映射

FieldValuesNotes
model
string, default 
"default"
Unknown model IDs fall back to Venice's default.
prompt
string, ≤ 1500 charsRequired.
size
auto
, 
256x256
, 
512x512
, 
1024x1024
, 
1536x1024
, 
1024x1536
, 
1792x1024
, 
1024x1792
—
output_format
jpeg
/ 
png
/ 
webp
Defaults to 
png
.
response_format
b64_json
/ 
url
url
returns a 
data:
URL (not a hosted URL).
moderation
auto
(safe mode on) / 
low
(safe mode off)		—
n
1
Venice only supports a single image per call here.
quality
, 
style
(
vivid
/
natural
), 
background
, 
output_compression
, 
user
—Accepted for OpenAI compat, not used by Venice.
If you need 
variants
, 
seed
, 
negative_prompt
, 
cfg_scale
, or 
style_preset
, switch to 
/image/generate
.
字段取值说明
model
string，默认值
"default"
未知模型ID会 fallback 到Venice的默认模型。
prompt
string，≤1500字符必填项。
size
auto
, 
256x256
, 
512x512
, 
1024x1024
, 
1536x1024
, 
1024x1536
, 
1792x1024
, 
1024x1792
—
output_format
jpeg
/ 
png
/ 
webp
默认值为
png
。
response_format
b64_json
/ 
url
url
返回的是
data:
URL（而非托管URL）。
moderation
auto
（安全模式开启）/ 
low
（安全模式关闭）		—
n
1
Venice在此接口中仅支持单次调用生成单张图像。
quality
, 
style
(
vivid
/
natural
), 
background
, 
output_compression
, 
user
—为兼容OpenAI而保留，但Venice不会使用这些参数。
如果你需要
variants
、
seed
、
negative_prompt
、
cfg_scale
或
style_preset
参数，请切换到
/image/generate
接口。

/image/styles
— list presets

/image/styles
— 获取风格预设列表

bash
curl https://api.venice.ai/api/v1/image/styles \
  -H "Authorization: Bearer $VENICE_API_KEY"
Returns a list of 
styles[]
, each with a 
name
you can pass to 
style_preset
. Cache this — it's small and stable.
bash
curl https://api.venice.ai/api/v1/image/styles \
  -H "Authorization: Bearer $VENICE_API_KEY"
返回
styles[]
列表，每个元素包含可传入
style_preset
的
name
值。建议缓存此结果——内容体量小且稳定。

Choosing a model

模型选择方法

bash
curl "https://api.venice.ai/api/v1/models?type=image" \
  -H "Authorization: Bearer $VENICE_API_KEY"
Inspect per-model 
model_spec
:
  • constraints.widthHeightDivisor
    — 
    width
    and 
    height
    must both be divisible by this.
  • constraints.aspectRatios[]
    + 
    defaultAspectRatio
    — if present, the model supports aspect-ratio-driven sizing.
  • constraints.resolutions[]
    + 
    defaultResolution
    — if present, the model supports 
    resolution
    (
    1K
    /
    2K
    /
    4K
    ).
  • constraints.steps.{default,max}
    — step bounds (some models ignore 
    steps
    entirely).
  • constraints.promptCharacterLimit
    — max prompt length (also applies to 
    negative_prompt
    ).
  • pricing.generation.usd
    — flat USD per image, or 
    pricing.resolutions[].usd
    for resolution-tiered models.
Pick a model that matches the feature + size combo you plan to use.
bash
curl "https://api.venice.ai/api/v1/models?type=image" \
  -H "Authorization: Bearer $VENICE_API_KEY"
查看每个模型的
model_spec
：
  • constraints.widthHeightDivisor
    — 
    width
    和
    height
    必须能被此值整除。
  • constraints.aspectRatios[]
    + 
    defaultAspectRatio
    — 如果存在，说明模型支持按宽高比设定尺寸。
  • constraints.resolutions[]
    + 
    defaultResolution
    — 如果存在，说明模型支持
    resolution
    参数（
    1K
    /
    2K
    /
    4K
    ）。
  • constraints.steps.{default,max}
    — 步数范围（部分模型会完全忽略
    steps
    参数）。
  • constraints.promptCharacterLimit
    — 提示词最大长度（同样适用于
    negative_prompt
    ）。
  • pricing.generation.usd
    — 单张图像的固定美元费用；对于按分辨率分层定价的模型，费用在
    pricing.resolutions[].usd
    中。
选择与你计划使用的功能+尺寸组合匹配的模型。

Common patterns

常见使用模式

Fixed-seed A/B test

固定种子值的A/B测试

json
{"model": "z-image-turbo", "prompt": "...", "seed": 42, "variants": 4}
json
{"model": "z-image-turbo", "prompt": "...", "seed": 42, "variants": 4}

Aspect-ratio-driven model (Nano Banana family)

按宽高比驱动的模型（Nano Banana系列）

json
{"model": "nano-banana-2", "prompt": "...", "aspect_ratio": "16:9", "resolution": "2K"}
(Other nano-banana variants: 
nano-banana-pro
. Always verify the current ID via 
GET /models?type=image
.)
json
{"model": "nano-banana-2", "prompt": "...", "aspect_ratio": "16:9", "resolution": "2K"}
（其他Nano Banana变体：
nano-banana-pro
。请始终通过
GET /models?type=image
验证当前模型ID。）

Style preset + negative

风格预设+负提示词

json
{
  "model": "z-image-turbo",
  "prompt": "a red sports car in a parking lot",
  "negative_prompt": "blurry, people, clouds",
  "style_preset": "3D Model"
}
json
{
  "model": "z-image-turbo",
  "prompt": "a red sports car in a parking lot",
  "negative_prompt": "blurry, people, clouds",
  "style_preset": "3D Model"
}

Stream binary to disk (Node)

将二进制流写入磁盘（Node.js）

ts
const res = 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: 'z-image-turbo', prompt: '...', return_binary: true }),
})
if (!res.ok) throw new Error(await res.text())
const buf = Buffer.from(await res.arrayBuffer())
await fs.writeFile('out.webp', buf)
ts
const res = 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: 'z-image-turbo', prompt: '...', return_binary: true }),
})
if (!res.ok) throw new Error(await res.text())
const buf = Buffer.from(await res.arrayBuffer())
await fs.writeFile('out.webp', buf)

Errors

错误码说明

CodeMeaning
400
Bad params (e.g. dimensions not divisible by 
widthHeightDivisor
, prompt too long, 
variants>1
with 
return_binary
).
401
Auth or Pro-only model.
402
Insufficient balance. Bearer: plain 
{ "error": "Insufficient balance" }
; x402: 
PAYMENT_REQUIRED
body + 
PAYMENT-REQUIRED
header.
415
Wrong 
Content-Type
(send 
application/json
for this endpoint).
429
Rate limited.
500
/ 
503
Inference or capacity issue — retry with jitter.
(Content-policy violations on 
/image/generate
come back as 
400
with an error string, not 
422
— the 
422
shape is specific to audio generation paths.)
状态码含义
400
参数错误（例如：尺寸无法被
widthHeightDivisor
整除、提示词过长、
return_binary
为true时
variants
大于1）。
401
认证失败或使用了仅Pro用户可用的模型。
402
余额不足。Bearer认证返回：
{ "error": "Insufficient balance" }
；x402返回：
PAYMENT_REQUIRED
响应体 + 
PAYMENT-REQUIRED
响应头。
415
Content-Type
错误（此接口需发送
application/json
格式）。
429
请求频率超限。
500
/ 
503
推理或容量问题 — 请添加抖动后重试。
（
/image/generate
接口的内容政策违规会返回
400
及错误字符串，而非
422
— 
422
状态码专用于音频生成路径的错误。）

Gotchas

注意事项

  • Each model picks one sizing idiom: either 
    width
    /
    height
    , 
    aspect_ratio
    + 
    resolution
    , or (OpenAI-compat) 
    size
    . Match the model's 
    constraints
    .
  • variants > 1
    requires 
    return_binary: false
    (JSON with base64 array).
  • steps
    is ignored by fast/turbo models; they hardcode step count internally.
  • hide_watermark: true
    is advisory — Venice may still watermark content flagged by safety classifiers.
  • Old 
    inpaint
    field is deprecated; don't use it.
  • For OpenAI-compat, 
    response_format: "url"
    returns a data URL, not a hosted URL — plan for that if you're saving to storage.
  • 每个模型仅支持一种尺寸设定方式：要么是
    width
    /
    height
    ，要么是
    aspect_ratio
    + 
    resolution
    ，要么是（兼容OpenAI的）
    size
    。请匹配模型的
    constraints
    参数。
  • variants > 1
    要求
    return_binary: false
    （返回包含base64数组的JSON）。
  • 快速/Turbo系列模型会忽略
    steps
    参数；它们在内部硬编码了步数。
  • hide_watermark: true
    仅为建议性设置 — 对于被安全分类器标记的内容，Venice仍可能添加水印。
  • 旧的
    inpaint
    字段已废弃，请不要使用。
  • 在兼容OpenAI的接口中，
    response_format: "url"
    返回的是data URL，而非托管URL — 如果要保存到存储系统，请对此做好适配。