Venice Image Generation

Two text-to-image endpoints:

1. POST /api/v1/image/generate — Venice-native, full control (negative prompts, CFG, seed, style presets/references, quality, 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. No auth required.

For editing / upscaling / multi-image / background removal, see 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.
• You want generated images to match the look of existing images (style_references).

/image/generate — Venice-native

Request

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
  }'

The request schema is strict: unknown fields are rejected with 400.

Fields

| Field | Type | Default | Notes |
|---|---|---|---|
| model | string | — | Required. Image model ID from GET /models?type=image. Unknown IDs return 404 (with a suggestion); retired IDs return 404 naming the replacement when one exists. |
| prompt | string | — | Required. Non-blank. Max constraints.promptCharacterLimit for the model (1,500 – 32,768 today). |
| negative_prompt | string | — | What not to show. Same character cap as prompt. Only used by some models today (e.g. venice-sd35, lustify-, wai-Illustrious, qwen-image-2, qwen-image-2-pro, qwen-image-3, qwen-image-3-pro, wan-2-7-). Silently dropped everywhere else, including z-image-turbo and chroma. |
| width, height | int | 1024, 1024 | ≤ 1280 each. Only used by pixel-sized models (no constraints.aspectRatios). Aspect-ratio models ignore them, and qwen-image, qwen-image-3, qwen-image-3-pro reject them with 400 — use aspect_ratio. |
| aspect_ratio | string | model default | E.g. "1:1", "16:9", "4:3". Send only values from the model's constraints.aspectRatios. /image/generate doesn't validate this field: most models fall back to defaultAspectRatio, but some pass it upstream and fail. |
| resolution | string | model default | "1K", "2K", "4K". Must be in the model's constraints.resolutions (otherwise 400). Silently dropped for models with no resolutions. |
| quality | "low"/"medium"/"high" | model default | Only for models with constraints.qualities (GPT Image 2 / 2.5, Ideogram V4.5, Grok Imagine 2.0). A value outside that list is 400; ignored on other models. Changes the price — see pricing.quality. |
| cfg_scale | number | model default | 0 < x ≤ 20. Higher = more prompt adherence. |
| steps | int | min(steps.max, 20) | Only used by models that take steps (today venice-sd35, lustify-*, wai-Illustrious); on those it is 1..constraints.steps.max and above max is 400. Every other model, including z-image-turbo and chroma, accepts any integer and ignores it. |
| seed | int | random | -999999999..999999999. Omit for a random seed (0 is a literal seed, not "random"). Some models ignore it (e.g. GPT Image, Muse, Luma, Recraft, ImagineArt, Seedream V5 Pro, Nano Banana Pro, Grok Imagine). |
| variants | int | 1 | 1–4. Only with return_binary: false. Only the first image uses your seed; the others get random seeds. Each variant is billed and rate-limited as one image. |
| style_preset | string | — | Exact value from GET /image/styles; anything else is 400. |
| style_references | array | — | Reference images that guide the aesthetic. Each item: { "image": , "strength": 0.1–1 (default 0.5) }. Only on models with supportsStyleReferences: true, max constraints.maxStyleReferences entries; otherwise 400. strength is ignored when constraints.supportsStyleReferenceStrength is false. |
| lora_strength | int | — | 0–100. Only applies to models that use LoRAs. |
| enhance_prompt | bool | false | Rewrites the prompt to add visual detail before generating. Adds up to ~30 s and a $0.04 charge when a rewrite is produced (fails open to your original prompt). The final prompt comes back URL-encoded in the x-venice-enhanced-prompt response header. |
| disable_prompt_optimization_thinking | bool | model default | Skip the model's prompt-optimization thinking step for speed. Only honored by models with supportsOptimizePromptThinking: true (e.g. seedream-v5-pro, qwen-image-3). |
| enable_web_search | bool | false | Only for models with supportsWebSearch: true (currently nano-banana-2, nano-banana-pro); ignored elsewhere. The spec warns that search can cost extra, but today the per-image charge is the same with or without it. |
| format | "webp"/"png"/"jpeg" | webp | Output image format. |
| return_binary | bool | false | true → raw image bytes; false → JSON with base64. |
| embed_exif_metadata | bool | false | Embed prompt info in EXIF. |
| hide_watermark | bool | false | Only matters on Venice's flat-priced models (z-image-turbo, venice-sd35, chroma, lustify-*, wai-Illustrious). All other models are never watermarked. Images classified as adult content and very small images are never watermarked either. |
| safe_mode | bool | true | Blurs images classified as adult content. |
| anon_user_id | string | — | Optional end-user identifier (printable ASCII, ≤ 128 chars, no \|\|) forwarded for upstream attribution. |
| inpaint | — | — | Removed (disabled May 19 2025). Sending it is a 400. Use /image/edit. |

Response (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)" } }
}

Send Accept-Encoding: gzip, br to get the JSON compressed.

With return_binary: true, the body is the raw image; Content-Type is detected from the bytes (image/webp, image/png, or image/jpeg).

Response headers

| Header | Meaning |
|---|---|
| x-venice-is-content-violation | "true" if the image was blocked. The call still returns 200: JSON images are blacked out; binary returns a PNG placeholder. You are not charged. |
| x-venice-is-blurred | "true" if safe_mode blurred the output. |
| x-venice-enhanced-prompt | URL-encoded rewritten prompt (only when enhance_prompt produced one). |
| x-venice-model-deprecation-warning, x-venice-model-deprecation-date, x-venice-deprecated, x-venice-deprecated-replacement | Present when the model is scheduled for or already in deprecation. |
| x-ratelimit-{limit,remaining,reset}-*, x-venice-balance-usd, x-venice-balance-diem | Rate-limit and balance state, set before the image is generated. |
| X-Balance-Remaining | Listed in the spec for x402 callers but not currently set by the server — poll GET /x402/balance/{walletAddress} instead. |

/images/generations — OpenAI-compatible

Use this if you're already on the OpenAI SDK. Field names match 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

Mapped fields

| Field | Values | Notes |
|---|---|---|
| model | string | Required in practice: omitting it (or sending "") returns 400 "model is required", even though the spec lists a "default" default. Unknown IDs (e.g. dall-e-3) silently fall back to Venice's default image model (z-image-turbo). |
| prompt | string, 1–1500 chars | Required. 1500 is the cap here regardless of model. |
| size | auto (default → 1024×1024), 256x256, 512x512, 1024x1024, 1536x1024, 1024x1536, 1792x1024, 1024x1792 | Mapped to width/height, so it only affects pixel-sized models; aspect-ratio models use their default aspect ratio. |
| output_format | jpeg / png / webp | Defaults to png. |
| response_format | b64_json (default) / url | url returns a data: URL (not a hosted URL). |
| moderation | auto (default, safe mode on) / low (safe mode off) | — |
| n | 1 | Only one image per call. |
| anon_user_id | string | Same as on /image/generate. |
| quality, style, background, output_compression, user | — | Accepted for OpenAI compatibility and ignored, but values must still be valid (quality: auto/high/medium/low/hd/standard; style: vivid/natural; background: transparent/opaque/auto; output_compression: 0–100). user is not used for inference and is not an alias of anon_user_id, but it does split the error budget per value (see venice-errors). |

Response: { "created": , "data": [{ "b64_json": "..." }] } (or [{ "url": "data:image/png;base64,..." }]). Images from this endpoint are never watermarked. Unknown fields are rejected with 400.

If you need variants, seed, negative_prompt, cfg_scale, aspect_ratio, resolution, quality, style_preset, or style_references, switch to /image/generate.

/image/styles — list presets

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

No API key needed. Returns a list of strings:

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

Pass any data[] entry verbatim as style_preset (it is case-sensitive). Cache it; the list rarely changes.

Choosing a model

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

Inspect each model's model_spec:

• constraints.promptCharacterLimit — max prompt length (also applies to negative_prompt).
• constraints.aspectRatios[] + defaultAspectRatio — present on aspect-ratio-driven models; use aspect_ratio instead of width/height.
• constraints.resolutions[] + defaultResolution — present when the model accepts resolution.
• constraints.qualities[] + defaultQuality — present when the model accepts quality.
• constraints.steps.{default,max} — step bounds. Every model lists them, but only a few use steps (see the field table).
• constraints.widthHeightDivisor — pixel-sized models work best with width/height as multiples of this (8 or 16). The API does not validate it.
• supportsStyleReferences, constraints.maxStyleReferences, constraints.supportsStyleReferenceStrength — style-reference support.
• supportsWebSearch, supportsOptimizePromptThinking — whether those request flags do anything.
• privacy (private / anonymized) and uncensored — privacy tier and content posture.
• Pricing: pricing.generation.usd (flat per image), or pricing.resolutions[tier].usd for resolution-tiered models, plus pricing.quality[tier][level].usd for quality-tiered models.

Representative IDs (verify with GET /models?type=image — the list changes often):

| Sizing idiom | Examples |
|---|---|
| width/height | z-image-turbo (default model), venice-sd35, chroma, lustify-v8 |
| aspect_ratio only | 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 only) |

bria-bg-remover also appears under type=image, but it is the background-removal model. Use it through /image/background-remove, not /image/generate.

Common patterns

Fixed-seed reproducibility

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

On models that honor seed (e.g. z-image-turbo, seedream-v4, nano-banana-2), the same model + prompt + seed + settings should reproduce the same image, though third-party models don't guarantee bit-identical output. With variants > 1, only the first image uses seed; the rest are random, so run separate calls with different seeds if you need each one reproducible.

Aspect-ratio + resolution model (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"}

Quality tier (GPT Image 2 / 2.5, Ideogram V4.5)

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

Omitting quality uses defaultQuality (high for the GPT Image and Ideogram V4.5 models). The price depends on both resolution and quality.

Style preset + negative

Use a model that honors negative_prompt (see the field table); z-image-turbo silently drops it.

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

Style references (match the look of existing images)

{
  "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 }
  ]
}

Describe the subject in the prompt; the references carry the style. Today the supporting models are krea-v2-large / krea-v2-medium (up to 3 refs, strength honored) and luma-uni-1 / luma-uni-1-max (up to 3 refs, strength ignored). All four are anonymized models. Re-check supportsStyleReferences via GET /models?type=image. The Krea V2 models add a small per-request surcharge when references are used; it isn't itemized in the /models pricing.

Stream binary to disk (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)

Errors

| Code | Meaning |
|---|---|
| 400 | Bad params: missing model, schema violation, unknown field, prompt too long, steps above max (on models that use steps), invalid style_preset, unsupported resolution/quality for the model, width/height sent to qwen-image/qwen-image-3/qwen-image-3-pro, variants with return_binary: true, style_references on an unsupported model or over the cap, unreachable/corrupt reference image. |
| 401 | Auth failed. |
| 402 | No credentials at all (x402 payment-requirements body + PAYMENT-REQUIRED header), insufficient balance (Bearer: "Insufficient USD or Diem balance…"; x402 wallet: PAYMENT_REQUIRED body + header), or the API key's USD/DIEM spend limit is reached. |
| 403 | The API key's modelPrivacy setting blocks this model (e.g. a PRIVATE_ONLY key calling an anonymized model), or the model is unavailable in your region or restricted for your account. |
| 404 | Model not found or retired (message names the replacement when there is one). On /images/generations, unknown IDs fall back to the default model instead. |
| 422 | Reference image too large in pixels (over 7680×4320). |
| 429 | Rate limited, or the upstream provider is overloaded (Retry-After is set). |
| 500 | Inference failed. |
| 503 | Model at capacity or offline. Retry with jitter. |

Content-policy violations are not an error on these endpoints. You get 200 with x-venice-is-content-violation: true and a blocked image, and no charge. See venice-errors for body shapes and retry strategy.

Gotchas

• Each model uses one sizing idiom: width/height, or aspect_ratio (+ resolution). Read constraints first. Sending width/height to an aspect-ratio model is silently ignored, except on qwen-image, qwen-image-3, and qwen-image-3-pro, where it is a 400.
• aspect_ratio isn't validated on /image/generate, so a value the model doesn't list usually falls back to its default without an error. A resolution or quality the model doesn't list is a 400.
• variants > 1 requires return_binary: false.
• Grok Imagine models return the provider's bytes unchanged when nothing is blurred, so the output format may not match format and EXIF isn't embedded. Trust Content-Type, or sniff the bytes.
• Always check x-venice-is-content-violation. A blocked image still arrives as a 200.
• style_references on a model without supportsStyleReferences: true is a 400, not a silent no-op.
• enhance_prompt bills $0.04 each time it produces a rewrite. Leave it off for cost- or latency-sensitive calls.
• For OpenAI-compat, response_format: "url" returns a data URL, not a hosted URL. Plan for that if you're saving to storage.