venice-image-generate

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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`](../venice-image-edit/SKILL.md).

## 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,
    "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": <raw base64, data URI, or http(s) URL; < 8 MB; not SVG>, "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`](../venice-image-edit/SKILL.md). |

### Response (JSON, `return_binary: false`)

```json
{
  "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()`.

```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',
})

From veniceai/skills, MIT.

More from veniceai/skills