Venice Image Generation

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.

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

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

| Field | Type | Default | Notes | |---|---|---|---| | 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 | int | 1024, 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 | number | model default | 0 < x ≤ 20. Higher = more prompt adherence. | | steps | int | 8 | Inference steps. Some models ignore it (e.g. Turbo). | | seed | int | 0 | -999999999..999999999. Use 0/omit for random. | | variants | int | 1 | 1–4. Only if return_binary: false. | | lora_strength | int | — | 0–100 when model uses Loras. | | style_preset | string | — | Value from GET /image/styles. | | style_references | array | — | Reference images that guide the aesthetic of the output. Each item: { "image": <base64 or http(s) URL, <8MB>, "strength": 0.1–1 (default 0.5) }. Only on models with supportsStyleReferences: true; per-model cap in constraints.maxStyleReferences. strength is ignored when constraints.supportsStyleReferenceStrength is false. | | quality | "low"/"medium"/"high" | — | Output quality on models that support it (e.g. GPT Image 2). Higher values can raise the request charge. | | enhance_prompt | bool | false | Rewrite the prompt to add clarifying visual detail before generating. Costs extra credits when a rewrite happens and adds up to ~30 s. The final prompt returns 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. | | 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. |

Response (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.

/images/generations — OpenAI-compatible

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

Mapped fields

| Field | Values | Notes | |---|---|---| | model | string, default "default" | Unknown model IDs fall back to Venice's default. | | prompt | string, ≤ 1500 chars | Required. | | 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, style_preset, or style_references, switch to /image/generate.

/image/styles — list presets

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.

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).
• supportsStyleReferences — whether the model accepts style_references on /image/generate.
• constraints.maxStyleReferences — max number of style reference images (only present on supporting models).
• constraints.supportsStyleReferenceStrength — whether per-reference strength is honored (only present on supporting models).
• 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.

Common patterns

Fixed-seed A/B test

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

Aspect-ratio-driven model (Nano Banana family)

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.)

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

Style references (match the look of existing images)

json
{
  "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. As of mid-2026 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 anonymized routing. Always re-verify via GET /models?type=image (supportsStyleReferences).

Stream binary to disk (Node)

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

| Code | Meaning | |---|---| | 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.)

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.
• style_references is silently unsupported outside the models flagged supportsStyleReferences: true; check the flag rather than trying and inspecting output. Each reference image must be < 8MB.
• For OpenAI-compat, response_format: "url" returns a data URL, not a hosted URL — plan for that if you're saving to storage.