venice-image-generate

Venice 图像生成

两个文生图端点：

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。

适用场景

• 需要根据文本提示生成图像。
• 需要在一次调用中生成多个变体。
• 正在从 OpenAI 的 images.generate 迁移，并希望无需改动 SDK 即可切换。
• 希望在选定风格预设前先浏览预设。
• 希望生成的图像与现有图像的风格一致（style_references）。

/image/generate — Venice 原生

请求

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,
    "seed": 123456789,
    "variants": 1,
    "format": "webp",
    "style_preset": "3D Model",
    "safe_mode": true
  }'

请求架构严格：未知字段会被拒绝，并返回 400。

字段

字段	类型	默认值	说明
model	string	—	必填。 来自 GET /models?type=image 的图像模型 ID。未知 ID 会返回 404（并提供建议）；已退役的 ID 会返回 404，并在存在替代项时指出替代项。
prompt	string	—	必填。 不能为空白。长度上限为该模型的 constraints.promptCharacterLimit（目前为 1,500–32,768）。
negative_prompt	string	—	不希望显示的内容。字符数上限与 prompt 相同。目前仅部分模型使用此字段（例如 venice-sd35、lustify-*、wai-Illustrious、qwen-image-2、qwen-image-2-pro、qwen-image-3、qwen-image-3-pro、wan-2-7-*）。其他模型都会静默忽略此字段，包括 z-image-turbo 和 chroma。
width, height	int	1024, 1024	每项均 ≤ 1280。仅像素尺寸模型使用（没有 constraints.aspectRatios 的模型）。宽高比模型会忽略这些值；qwen-image、qwen-image-3、qwen-image-3-pro 则会以 400 拒绝这些值——请使用 aspect_ratio。
aspect_ratio	string	模型默认值	例如 "1:1"、"16:9"、"4:3"。只能发送模型 constraints.aspectRatios 中的值。/image/generate 不会验证此字段：大多数模型会回退到 defaultAspectRatio，但有些模型会将其传递给上游并导致失败。
resolution	string	模型默认值	"1K"、"2K"、"4K"。必须是模型 constraints.resolutions 中的值（否则返回 400）。对于没有 resolutions 的模型，此字段会被静默忽略。
quality	"low"/"medium"/"high"	模型默认值	仅适用于具有 constraints.qualities 的模型（GPT Image 2 / 2.5、Ideogram V4.5、Grok Imagine 2.0）。不在该列表中的值会返回 400；其他模型会忽略此字段。此项会影响价格——参见 pricing.quality。
cfg_scale	number	模型默认值	0 < x ≤ 20。值越高，对提示词的遵循程度越高。
steps	int	min(steps.max, 20)	仅供使用步数的模型使用（目前为 venice-sd35、lustify-*、wai-Illustrious）；这些模型的取值范围为 1..constraints.steps.max，超过最大值会返回 400。其他所有模型（包括 z-image-turbo 和 chroma）都接受任意整数并忽略此字段。
seed	int	随机	-999999999..999999999。省略时使用随机种子（0 是字面种子值，不表示“随机”）。部分模型会忽略此字段（例如 GPT Image、Muse、Luma、Recraft、ImagineArt、Seedream V5 Pro、Nano Banana Pro、Grok Imagine）。
variants	int	1	1–4。仅当 return_binary: false 时可用。只有第一张图像使用你提供的 seed；其余图像使用随机种子。每个变体都按一张图像计费并受速率限制。
style_preset	string	—	来自 GET /image/styles 的精确值；其他值会返回 400。
style_references	array	—	用于引导美学风格的参考图像。每项格式为：{ "image": <原始 base64、data URI 或 http(s) URL；< 8 MB；不能是 SVG>, "strength": 0.1–1（默认值为 0.5） }。仅适用于 supportsStyleReferences: true 的模型，条目数上限为 constraints.maxStyleReferences；否则返回 400。当 constraints.supportsStyleReferenceStrength 为 false 时，会忽略 strength。
lora_strength	int	—	0–100。仅适用于使用 LoRA 的模型。
enhance_prompt	bool	false	在生成前改写提示词，添加视觉细节。最多增加约 30 秒耗时；生成改写内容时会额外收取 $0.04（改写失败时会回退到原始提示词）。最终提示词会以 URL 编码形式包含在响应头 x-venice-enhanced-prompt 中。
disable_prompt_optimization_thinking	bool	模型默认值	跳过模型的提示词优化思考步骤，以加快速度。仅 supportsOptimizePromptThinking: true 的模型会遵循此设置（例如 seedream-v5-pro、qwen-image-3）。
enable_web_search	bool	false	仅适用于 supportsWebSearch: true 的模型（目前为 nano-banana-2、nano-banana-pro）；其他模型会忽略此字段。规范提示搜索可能产生额外费用，但目前开启或关闭搜索的单张图像费用相同。
format	"webp"/"png"/"jpeg"	webp	输出图像格式。
return_binary	bool	false	true → 原始图像字节；false → 包含 base64 的 JSON。
embed_exif_metadata	bool	false	在 EXIF 中嵌入提示词信息。
hide_watermark	bool	false	仅对 Venice 的固定价格模型（z-image-turbo、venice-sd35、chroma、lustify-*、wai-Illustrious）有效。其他所有模型都不会添加水印。被分类为成人内容的图像和非常小的图像也不会添加水印。
safe_mode	bool	true	对被分类为成人内容的图像进行模糊处理。
anon_user_id	string	—	可选的最终用户标识符（可打印的 ASCII 字符，≤ 128 个字符，不能包含 ||），会转发以供上游归因。
inpaint	—	—	已移除（于 2025 年 5 月 19 日禁用）。发送此字段会返回 400。请使用 /image/edit。

响应（JSON，return_binary: false）

{
  "id": "...",
  "images": ["<base64>", "<base64>"],
  "timing": { "inferenceDuration": 0, "inferencePreprocessingTime": 0, "inferenceQueueTime": 0, "total": 0 },
  "request": { "success": true, "data": { "...": "the parsed request with defaults filled in (style_references omitted)" } }
}

发送 Accept-Encoding: gzip, br 以获取压缩后的 JSON。

设置 return_binary: true 时，响应正文为原始图像；系统会根据字节检测 Content-Type（image/webp、image/png 或 image/jpeg）。

响应标头

标头	含义
x-venice-is-content-violation	如果图像被拦截，则为 "true"。调用仍会返回 200：JSON 图像会被涂黑；二进制响应会返回 PNG 占位图。不会向你收费。
x-venice-is-blurred	如果 safe_mode 模糊了输出，则为 "true"。
x-venice-enhanced-prompt	经过 URL 编码的重写提示词（仅当 enhance_prompt 生成了重写结果时）。
x-venice-model-deprecation-warning、x-venice-model-deprecation-date、x-venice-deprecated、x-venice-deprecated-replacement	当模型计划弃用或已经弃用时提供。
x-ratelimit-{limit,remaining,reset}-*、x-venice-balance-usd、x-venice-balance-diem	速率限制和余额状态，在生成图像前设置。
X-Balance-Remaining	该标头列在 x402 调用方的规范中，但服务端目前不会设置；请改为轮询 GET /x402/balance/{walletAddress}。

/images/generations — 兼容 OpenAI

如果你已经在使用 OpenAI SDK，请使用此接口。字段名称与 openai.images.generate() 相同。

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

映射字段

字段	值	说明
model	字符串	实际上必填：省略此字段（或发送 ""）会返回 400 "model is required"，尽管规范将 "default" 列为默认值。未知 ID（如 dall-e-3）会静默回退到 Venice 的默认图像模型（z-image-turbo）。
prompt	字符串，1–1500 个字符	必填。无论模型如何，此处上限均为 1500。
size	auto（默认 → 1024×1024）、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	每次调用只能生成一张图像。
anon_user_id	字符串	与 /image/generate 中的含义相同。
quality、style、background、output_compression、user	—	为兼容 OpenAI 而接受，但会被忽略；不过值仍必须有效（quality：auto/high/medium/low/hd/standard；style：vivid/natural；background：transparent/opaque/auto；output_compression：0–100）。user 不用于推理，也不是 anon_user_id 的别名，但会按值拆分错误预算（参见 venice-errors）。

响应：{ "created": <unix>, "data": [{ "b64_json": "..." }] }（或 [{ "url": "data:image/png;base64,..." }]）。此接口生成的图像不会添加水印。未知字段会被拒绝，并返回 400。

如果需要 variants、seed、negative_prompt、cfg_scale、aspect_ratio、resolution、quality、style_preset 或 style_references，请改用 /image/generate。

/image/styles — 列出预设

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

无需 API 密钥。返回一个字符串列表：

{ "object": "list", "data": ["3D Model", "Analog Film", "Anime", "Cinematic", "Comic Book", "..."] }

将任意 data[] 条目原样传递为 style_preset（区分大小写）。请缓存该列表；它很少变化。

选择模型

curl "https://api.venice.ai/api/v1/models?type=image"

检查各个模型的 model_spec：

• constraints.promptCharacterLimit — 提示词的最大长度（也适用于 negative_prompt）。
• constraints.aspectRatios[] + defaultAspectRatio — 用于由宽高比驱动的模型；应使用 aspect_ratio，而不是 width/height。
• constraints.resolutions[] + defaultResolution — 用于接受 resolution 的模型。
• constraints.qualities[] + defaultQuality — 用于接受 quality 的模型。
• constraints.steps.{default,max} — 步数范围。每个模型都会列出这些值，但只有少数模型会用到 steps（参见字段表）。
• constraints.widthHeightDivisor — 对于按像素尺寸设置的模型，width/height 最好为该值（8 或 16）的倍数。API 不会对此进行验证。
• supportsStyleReferences、constraints.maxStyleReferences、constraints.supportsStyleReferenceStrength — 对风格参考的支持情况。
• supportsWebSearch、supportsOptimizePromptThinking — 这些请求标志是否有效。
• privacy（private / anonymized）和 uncensored — 隐私级别和内容策略。
• 定价：pricing.generation.usd（每张图片固定价格），或按分辨率分级模型的 pricing.resolutions[tier].usd，以及按质量分级模型的 pricing.quality[tier][level].usd。

代表性 ID（请通过 GET /models?type=image 验证——列表经常变动）：

尺寸设置方式	示例
width/height	z-image-turbo（默认模型）、venice-sd35、chroma、lustify-v8
仅 aspect_ratio	flux-2-pro、seedream-v5-lite、muse-image、qwen-image-2、krea-v2-large
aspect_ratio + resolution	nano-banana-2、nano-banana-pro、seedream-v5-pro、qwen-image-3
aspect_ratio + resolution + quality	gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst、ideogram-v4-5（1K / 2K）、grok-imagine-image-2-0（仅 low/medium）

bria-bg-remover 也会出现在 type=image 下，但它是背景移除模型。请通过 /image/background-remove 使用它，而不是 /image/generate。

常见模式

固定种子以实现可复现性

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

对于支持 seed 的模型（例如 z-image-turbo、seedream-v4、nano-banana-2），相同的模型、提示词、种子和设置应生成相同的图片，但第三方模型不保证输出完全一致。设置 variants > 1 时，只有第一张图片会使用 seed；其余图片使用随机种子，因此，如果需要每张图片都可复现，请使用不同的种子分别调用。

宽高比 + 分辨率模型（Nano Banana、Seedream V5 Pro）

{"model": "nano-banana-2", "prompt": "...", "aspect_ratio": "16:9", "resolution": "2K"}

{"model": "seedream-v5-pro", "prompt": "...", "aspect_ratio": "4:3", "resolution": "2K"}

质量分级（GPT Image 2 / 2.5、Ideogram V4.5）

{"model": "gpt-image-2-5-flare", "prompt": "...", "aspect_ratio": "3:2", "resolution": "2K", "quality": "medium"}

省略 quality 时会使用 defaultQuality（GPT Image 和 Ideogram V4.5 模型的默认值为 high）。价格取决于分辨率和质量。

风格预设 + 负面提示词

使用支持 negative_prompt 的模型（参见字段表）；z-image-turbo 会静默忽略它。

{
  "model": "venice-sd35",
  "prompt": "a red sports car in a parking lot",
  "negative_prompt": "blurry, people, clouds",
  "style_preset": "3D Model"
}

风格参考（匹配现有图片的风格）

{
  "model": "krea-v2-large",
  "prompt": "a lighthouse on a rocky coast at dusk",
  "style_references": [
    { "image": "https://example.com/ref-1.png", "strength": 0.8 },
    { "image": "data:image/png;base64,....", "strength": 0.4 }
  ]
}

在提示词中描述主体；参考图片会提供风格。目前，支持的模型包括 krea-v2-large / krea-v2-medium（最多 3 张参考图片，会应用强度设置）以及 luma-uni-1 / luma-uni-1-max（最多 3 张参考图片，不应用强度设置）。这 4 个模型均为 anonymized 模型。请通过 GET /models?type=image 重新检查 supportsStyleReferences。使用参考图片时，Krea V2 模型会收取少量的每请求附加费；该费用不会在 /models 定价中单独列出。

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

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())
if (res.headers.get('x-venice-is-content-violation') === 'true') throw new Error('Content violation')
const ext = (res.headers.get('content-type') ?? 'image/webp').split('/')[1]
const buf = Buffer.from(await res.arrayBuffer())
await fs.writeFile(`out.${ext}`, buf)

错误

代码	含义
400	参数错误：缺少 model、违反架构、未知字段、提示词过长、steps 超出上限（适用于使用 steps 的模型）、style_preset 无效、模型不支持 resolution/quality、向 qwen-image/qwen-image-3/qwen-image-3-pro 发送了 width/height、return_binary: true 时使用了 variants、在不支持的模型上使用 style_references 或超出上限、参考图像无法访问或已损坏。
401	身份验证失败。
402	完全没有凭据（x402 付款要求正文 + PAYMENT-REQUIRED 标头）、余额不足（Bearer："Insufficient USD or Diem balance…"；x402 钱包：PAYMENT_REQUIRED 正文 + 标头），或 API 密钥的 USD/DIEM 消费限额已达到。
403	API 密钥的 modelPrivacy 设置禁止使用此模型（例如，PRIVATE_ONLY 密钥调用 anonymized 模型），或模型在你所在的区域不可用，或你的账户受到限制。
404	找不到模型或模型已停用（如果有替代模型，消息中会注明）。在 /images/generations 上，未知 ID 会回退到默认模型。
422	参考图像的像素尺寸过大（超过 7680×4320）。
429	请求受到速率限制，或上游提供商过载（会设置 Retry-After）。
500	推理失败。
503	模型已达容量上限或处于离线状态。请加入随机抖动后重试。

在这些端点上，违反内容政策不算错误。你会收到状态码 200、x-venice-is-content-violation: true 和被拦截的图像，且不会产生费用。有关正文格式和重试策略，请参阅 venice-errors。

注意事项

• 每个模型使用一种尺寸指定方式：width/height，或 aspect_ratio（加上 resolution）。请先阅读 constraints。向宽高比模型发送 width/height 会被静默忽略，但 qwen-image、qwen-image-3 和 qwen-image-3-pro 除外，这些模型会返回 400。
• /image/generate 不会验证 aspect_ratio，因此模型未列出的值通常会回退到默认值，不会报错。模型未列出的 resolution 或 quality 会返回 400。
• variants > 1 要求 return_binary: false。
• 如果没有内容被模糊处理，Grok Imagine 模型会原样返回提供商的字节数据，因此输出格式可能与 format 不符，且不会嵌入 EXIF。请以 Content-Type 为准，或检查字节数据以识别格式。
• 务必检查 x-venice-is-content-violation。被拦截的图像仍会以状态码 200 返回。
• 在 supportsStyleReferences: true 的模型之外使用 style_references 会返回 400，而非静默无操作。
• 每次 enhance_prompt 生成改写内容都会收费 $0.04。对于注重成本或延迟的请求，请将其关闭。
• 对于 OpenAI 兼容模式，response_format: "url" 返回的是数据 URL，而不是托管 URL。如果要保存到存储中，请考虑这一点。