Bildgenerierung

Die Bildgenerierung auf Venice ist synchron. Sende einen Prompt an /image/generate und erhalte dein Bild in derselben Antwort – entweder als Base64 in JSON oder als rohes Binary, wenn return_binary auf true steht.

Endpoints

Endpoint	Zweck	Wann verwenden
`POST /image/generate`	Native Venice-Bildgenerierungs-API	Für vollständigen Feature-Support
`GET /image/styles`	Verfügbare Style-Presets auflisten	Vor dem Senden von `style_preset`
`POST /images/generations`	OpenAI-kompatible Bildgenerierungs-API	Für Migration bestehender OpenAI-Image-Clients

Schritt 1: Generierungsanfrage senden

Die Größenangabe ist modellspezifisch. Manche Modelle akzeptieren explizite width und height; manche stellen aspect_ratio bereit; und Resolution-Tier-Modelle bieten aspect_ratio plus resolution-Werte wie 1K, 2K oder 4K.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo und qwen-image-2-1-pro akzeptieren width oder height nicht mehr. Das Senden eines der beiden gibt 400 mit “width and height are no longer supported for this model. Use aspect_ratio instead.” zurück. Prüfe model_spec.constraints aus GET /models?type=image, bevor du die Größenfelder wählst.

Beispiel für Pixel-basierte Größe:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "venice-sd35",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
  "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

Beispiel für Aspect-Ratio-Größe:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-image-2",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "format": "webp"
}

Beispiel für Resolution-Tier-Größe:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "format": "png"
}

Dasselbe Muster gilt für andere Resolution-Tier-Modelle:

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Nutze Image-Modelle oder die Models-API, um zu prüfen, welche Größenfelder ein Modell akzeptiert. Antwort (200):

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

Das images-Array enthält Base64-kodierte Bilddaten. Dekodiere den ersten Eintrag, um das Bild zu speichern oder anzuzeigen. timing.total ist die vollständige Request-Dauer in Millisekunden.

Schritt 2: Bild dekodieren und speichern

import base64
import os
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/image/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "venice-sd35",
        "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
        "width": 1024,
        "height": 1024,
        "format": "webp",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0])

with open("output.webp", "wb") as f:
    f.write(image_bytes)

print(f"Saved image from request {data['id']}")

import fs from "fs";

const response = 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: "venice-sd35",
    prompt: "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
    width: 1024,
    height: 1024,
    format: "webp",
  }),
});

const data = await response.json();
const imageBuffer = Buffer.from(data.images[0], "base64");
fs.writeFileSync("output.webp", imageBuffer);

console.log(`Saved image from request ${data.id}`);

Schritt 3: Binary statt JSON zurückgeben (optional)

Wenn der Response-Body die Bilddatei selbst sein soll, setze return_binary: true. Das ist nützlich, wenn du das Bild direkt streamen oder speichern willst, ohne Base64 zu dekodieren.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.png \
  -d '{
    "model": "qwen-image-2",
    "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones",
    "format": "png",
    "return_binary": true
  }'

Wenn return_binary auf true steht, ist der Response-Body rohe image/jpeg-, image/png- oder image/webp-Daten – je nach angefordertem format.

variants wird nur unterstützt, wenn return_binary auf false steht.

Schritt 4: Verfügbare Image-Styles auflisten (optional)

Wenn du style_preset nutzen willst, frage zuerst die verfügbaren Styles über /image/styles ab:

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

Dieser Endpoint ist öffentlich und erfordert keinen API-Schlüssel. Antwort (200):

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

Die Style-Namen befinden sich in data, nicht auf der obersten Ebene – lies response.data, statt direkt über das Response-Objekt zu iterieren. Übergib dann einen dieser Werte in deiner Generierungsanfrage:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

Nutze den Styles-Endpoint, wenn du exakte Preset-Namen brauchst, statt sie zu raten.

Request-Parameter

Parameter	Typ	Pflicht	Default	Beschreibung
`model`	string	Ja	-	Modell-ID für die Generierung
`prompt`	string	Ja	-	Was generiert werden soll
`negative_prompt`	string	Nein	-	Was im Bild vermieden werden soll
`width`	integer	Nein	`1024`	Ausgabebreite in Pixeln für Pixel-basierte Modelle wie `venice-sd35`. Wird von der Qwen-Image-Familie abgelehnt – siehe Hinweis unten
`height`	integer	Nein	`1024`	Ausgabehöhe in Pixeln für Pixel-basierte Modelle wie `venice-sd35`. Wird von der Qwen-Image-Familie abgelehnt – siehe Hinweis unten
`format`	string	Nein	`webp`	Ausgabeformat: `jpeg`, `png` oder `webp`
`variants`	integer	Nein	`1`	Anzahl zu generierender Bilder (`1`–`4`), nur wenn `return_binary` `false` ist. Eine explizite Ablehnung durch die Inhaltsrichtlinie des Providers kann einzelne Varianten auslassen; siehe Teilweise Varianten-Ergebnisse
`return_binary`	boolean	Nein	`false`	Rohe Image-Bytes statt Base64-JSON zurückgeben
`safe_mode`	boolean	Nein	`true`	Adult-Inhalte unscharf machen, wenn aktiviert
`seed`	integer	Nein	zufällig	Denselben Seed wiederverwenden für konsistentere Iterationen
`cfg_scale`	number	Nein	modellabhängig	Höhere Werte zwingen das Modell, dem Prompt enger zu folgen
`lora_strength`	integer	Nein	-	Stärke (`0`-`100`) der zusätzlichen LoRAs, die ein Modell verwendet. Siehe LoRA-Stärke
`style_preset`	string	Nein	-	Voreingestellten Stil aus Image Styles anwenden
`style_references`	array	Nein	-	Style-Referenzbilder, die die Ästhetik der Ausgabe steuern. Jeder Eintrag ist `{ "image": <url or base64>, "strength": <0.1-1> }`. Nur bei unterstützten Modellen; siehe Style-Referenzen
`aspect_ratio`	string	Bedingt	-	Wird von Modellen mit Ratio-basierter Größe verwendet, z. B. `qwen-image-2`, `gpt-image-2`, `nano-banana-2` und `nano-banana-pro`
`resolution`	string	Bedingt	-	Wird von Modellen mit Resolution-Tiers wie `1K`, `2K` oder `4K` verwendet
`enable_web_search`	boolean	Bedingt	`false`	Ermöglicht unterstützten Modellen die Nutzung aktueller Web-Informationen; erzeugt Zusatzkosten
`transparent_background`	boolean	Nein	`false`	Ein PNG oder WebP mit echtem Alphakanal zurückgeben. Erfordert ein Modell mit `supportsTransparentBackground: true` und `format` `png` oder `webp`. Siehe Bilder mit transparentem Hintergrund

Die Validierung ist modellspezifisch. Prüfe Image-Modelle und die Models-API, bevor du dich quer über mehrere Modelle auf einen Parameter verlässt.

Modellspezifische Optionen

Hochauflösende Generierung

Manche Image-Modelle unterstützen aspect_ratio ohne wählbare resolution-Stufe. Beispiel: qwen-image-2 akzeptiert eine Aspect-Ratio und mappt sie auf modellspezifische Ausgabedimensionen:

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

Andere Image-Modelle unterstützen aspect_ratio plus eine resolution-Stufe. Beispiel: gpt-image-2, nano-banana-2 und nano-banana-pro unterstützen 1K, 2K und 4K:

{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Nutze Image-Modelle, um zu sehen, welche Modelle höhere Auflösungen unterstützen und wie sie bepreist werden.

LoRA-Stärke

Einige Bildmodelle wenden zusätzliche LoRAs an. lora_strength (integer, 0 bis 100) legt fest, wie stark sie angewendet werden, und wirkt sich nur auf Modelle aus, die sie verwenden. Die API akzeptiert keine eigenen LoRA-Dateien, und kein Endpoint listet die LoRAs auf, die ein Modell verwendet. lora_strength ist die einzige LoRA-Steuerung.

Adult-Inhalte und Safe Mode

safe_mode steuert, ob Adult-Inhalte in der Generierungsausgabe unscharf gemacht werden. Der Default ist true, daher kommen als Adult eingestufte Bilder unscharf zurück, sofern du nicht safe_mode: false sendest:

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

Nicht unscharfe Adult-Bilder (NSFW) stehen allen API-Nutzern zur Verfügung. Du brauchst kein Pro-Abo, und die Einstellung für den Filter für Inhalte für Erwachsene in der Venice-App hat keinen Einfluss auf Bildanfragen über die API. Manche Image-Modelle sind speziell für Adult-/unzensierte Generierung ausgelegt und passen gut zu safe_mode: false. Beispiele auf der Pricing-Seite sind lustify-sdxl, lustify-v7 und lustify-v8. Die aktuelle Liste und die Kosten pro Modell findest du unter Image-Modelle und Pricing. Für das Bearbeiten bestehender Bilder ist das Default-Edit-Modell firered-image-edit. Die Inhaltsrichtlinien variieren je nach Edit-Modell; wenn du unzensiertes Editing brauchst, nutze qwen-edit-uncensored über Image Editing. Wenn safe_mode aktiv ist und das Modell eine unscharfe oder moderierte Ausgabe zurückgibt, kannst du die Response-Header x-venice-is-blurred und x-venice-is-content-violation prüfen, falls du das programmatisch erkennen musst.

Du nutzt eine Drittanbieter-App? Adult-Bilder bleiben unscharf, sofern die App nicht safe_mode: false oder beim OpenAI-kompatiblen Endpoint moderation: "low" sendet (siehe unten).

Style-Presets

Wenn das gewählte Modell es unterstützt, kannst du mit style_preset die Ausgabe steuern, ohne deinen gesamten Prompt umzuschreiben. Gültige Preset-Namen findest du unter Image Styles:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

Die aktuelle Style-Liste findest du unter Image Styles.

Style-Referenzen

style_references geht einen Schritt weiter als style_preset: Statt eines benannten Presets richtet sich die Generierung an einem oder mehreren Referenzbildern aus. Jeder Eintrag hat ein image und optional eine strength:

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

Feld	Typ	Pflicht	Beschreibung
`image`	string	Ja	Referenzbild als `http://`- oder `https://`-URL, Base64-String oder Base64-Data-URI. Muss ein Rasterbild sein (JPEG, PNG, WebP, HEIF, HEIC oder AVIF), darf kein SVG sein und muss kleiner als 8 MB sein
`strength`	number	Nein	Wie stark die Referenz die Ausgabe beeinflusst, von `0.1` bis `1`. Default ist `0.5`. Wird von Modellen ignoriert, bei denen `supportsStyleReferenceStrength` `false` ist

Die Unterstützung hängt vom Modell ab. Prüfe GET /models?type=image:

model_spec.supportsStyleReferences ist nur bei Modellen true, die das Feld akzeptieren.
model_spec.constraints.maxStyleReferences gibt an, wie viele Einträge das Modell akzeptiert.
model_spec.constraints.supportsStyleReferenceStrength zeigt dir, ob strength überhaupt eine Wirkung hat.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

Wenn du style_references an ein Modell ohne Unterstützung sendest, bekommst du einen 400. Dasselbe gilt, wenn du das Limit des Modells überschreitest oder eine beschädigte, nicht erreichbare oder zu große Referenz sendest. Manche Modelle berechnen zusätzlich zum Basispreis pro Bild eine Style-Referenz-Gebühr für jedes zurückgegebene Bild, zum Beispiel Krea v2 Large und Krea v2 Medium. Die Gebühr fällt nur für Bilder an, die tatsächlich zurückgegeben werden. Die Basispreise pro Bild findest du unter Image-Modelle.

Teilweise Varianten-Ergebnisse

Bei variants größer als 1 können einzelne Varianten von der Inhaltsrichtlinie des Providers abgelehnt werden, während die übrigen erfolgreich sind. In diesem Fall gibt der Endpoint trotzdem 200 zurück, allerdings mit weniger Bildern als angefordert:

Wenn eine oder mehrere Varianten ausgelassen werden, enthält der JSON-Body content_policy_violation_count, also die Anzahl der ausgelassenen Varianten.
Der Response-Header x-venice-content-violation-count enthält dieselbe Anzahl.
x-venice-is-content-violation und x-venice-is-blurred beziehen sich auf die zurückgegebenen Bilder.

Werden alle angeforderten Varianten abgelehnt, werden keine Bilder zurückgegeben und die Anfrage schlägt stattdessen mit 422 fehl. Geh nicht davon aus, dass len(images) == variants gilt; vergleiche die Länge des Arrays mit variants und prüfe, falls vorhanden, content_policy_violation_count.

OpenAI-kompatibler Endpoint

Wenn du bereits OpenAI-Image-SDKs oder bestehende DALL-E-Integrationen verwendest, unterstützt Venice auch POST /images/generations. Das Request-Format ist einfacher, bietet aber weniger Features als der native Venice-Endpoint. Request:

{
  "model": "z-image-turbo",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

size gilt nur für pixelbasierte Modelle, die in model_spec.constraints aus GET /models?type=image einen widthHeightDivisor größer als 1 haben. Die meisten Modelle, darunter qwen-image-2, bestimmen die Ausgabegröße stattdessen über Seitenverhältnis und Auflösung und ignorieren size. Manche OpenAI-Parameter werden aus Gründen der SDK-Kompatibilität akzeptiert, aber ignoriert (n ist auf 1 beschränkt):

Parameter	Verhalten auf `/images/generations`
`quality`	Wird akzeptiert und ignoriert. Abgerechnet wird die Default-Qualitätsstufe des Modells
`style`	Wird akzeptiert und ignoriert
`output_compression`	Wird akzeptiert und ignoriert
`user`	Wird akzeptiert, verworfen und ist kein Alias für `anon_user_id`
`n`	Nur `1` wird unterstützt; andere Werte werden von der Validierung abgelehnt

Auf dieser Route gibt es keine Steuerung der Stufen: Es gibt kein Feld resolution oder aspect_ratio, und quality kann die Kosten weder erhöhen noch senken. Nutze bei GPT-Image-Modellen mit Stufen den nativen Endpoint /image/generate, wenn du quality, resolution oder aspect_ratio wählen willst. Nutze die OpenAI-kompatible Route für schnellere Migrationen. Verwende /image/generate, wenn du Venice-spezifische Optionen wie cfg_scale, style_preset, style_references, variants oder Binary-Responses brauchst.

Adult-Content-Unschärfe auf `/images/generations` steuern

Der OpenAI-kompatible Endpoint akzeptiert safe_mode nicht. Wird er gesendet, gibt es einen 400 mit Unrecognized key(s) in object: 'safe_mode'. Nutze stattdessen den OpenAI-typischen Parameter moderation:

Wert	Verhalten
`auto` (Default)	Macht Adult-Inhalte unscharf, wie `safe_mode: true`
`low`	Liefert die Ausgabe ohne Unschärfe, wie `safe_mode: false`

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode funktioniert nur auf dem nativen Endpoint POST /image/generate. moderation funktioniert nur auf dem OpenAI-kompatiblen Endpoint POST /images/generations. Dieselbe Aufteilung gilt für Transparenz: /image/generate verwendet transparent_background: true, während /images/generations den OpenAI-typischen Parameter background: "transparent" nutzt. Beide erfordern das Ausgabeformat png oder webp und ein Modell mit supportsTransparentBackground: true. Siehe Bilder mit transparentem Hintergrund.

Prompting-Tipps

Mit dem Motiv beginnen, dann Medium, Beleuchtung, Komposition und Stimmung ergänzen.
Zu vermeidende Details ins negative_prompt stecken, statt den Hauptprompt zu überladen.
seed beim Iterieren wiederverwenden, um Prompt-Änderungen zu vergleichen, ohne die Komposition komplett zu wechseln.
Größenangabe modellbewusst halten. Manche Modelle nutzen width/height, manche aspect_ratio, Resolution-Tier-Modelle aspect_ratio plus resolution.
variants beim Explorieren nutzen, dann auf eine einzelne Ausgabe zurückwechseln, sobald die Richtung steht.

Fehler

Status	Bedeutung	Aktion
`400`	Ungültige Request-Parameter	Feldnamen, Typen und modellspezifische Constraints prüfen
`401`	Authentifizierung fehlgeschlagen oder Modell benötigt höhere Access-Tier	API-Schlüssel und Modellzugang prüfen
`402`	Unzureichendes Guthaben	Credits unter venice.ai/settings/api aufladen
`404`	Unbekanntes Modell	Modell-ID mit `GET /models?type=image` abgleichen
`415`	Ungültiger Content-Type	JSON mit `Content-Type: application/json` senden
`422`	Verstoß gegen Inhaltsrichtlinie	Der Provider hat den Prompt oder das Bild explizit abgelehnt. Prompt anpassen oder Modell wechseln. Der Body enthält `error` und ein boolesches `retryable` und kann außerdem `suggested_prompt` und `recommended_model` enthalten
`429`	Rate-Limit überschritten oder Modell überlastet	Mit Backoff erneut versuchen; `Retry-After`-Header beachten
`500`	Inferenz-Verarbeitung fehlgeschlagen	Request wiederholen
`503`	Modell ausgelastet	Nach kurzer Verzögerung erneut versuchen

Wenn safe_mode aktiviert ist (oder moderation auf auto steht), prüfe Response-Header wie x-venice-is-blurred und x-venice-is-content-violation, wenn du Moderationsergebnisse programmatisch erkennen musst.

Verfügbare Modelle

Aktuelle Modellliste, Preise und Feature-Support unter Image-Modelle.

Dokumentation

Erste Schritte

Text & Chat

Bild

Video

Audio

Suche & RAG

Agenten & Integrationen

Coding-Tools

Agenten-Tools

SDKs & Frameworks

Endpoints

Schritt 1: Generierungsanfrage senden

Schritt 2: Bild dekodieren und speichern

Schritt 3: Binary statt JSON zurückgeben (optional)

Schritt 4: Verfügbare Image-Styles auflisten (optional)

Request-Parameter

Modellspezifische Optionen

Hochauflösende Generierung

LoRA-Stärke

Adult-Inhalte und Safe Mode

Style-Presets

Style-Referenzen

Teilweise Varianten-Ergebnisse

OpenAI-kompatibler Endpoint

Adult-Content-Unschärfe auf `/images/generations` steuern

Prompting-Tipps

Fehler

Verfügbare Modelle

​Endpoints

​Schritt 1: Generierungsanfrage senden

​Schritt 2: Bild dekodieren und speichern

​Schritt 3: Binary statt JSON zurückgeben (optional)

​Schritt 4: Verfügbare Image-Styles auflisten (optional)

​Request-Parameter

​Modellspezifische Optionen

​Hochauflösende Generierung

​LoRA-Stärke

​Adult-Inhalte und Safe Mode

​Style-Presets

​Style-Referenzen

​Teilweise Varianten-Ergebnisse

​OpenAI-kompatibler Endpoint

​Adult-Content-Unschärfe auf /images/generations steuern

​Prompting-Tipps

​Fehler

​Verfügbare Modelle

Endpoints

Schritt 1: Generierungsanfrage senden

Schritt 2: Bild dekodieren und speichern

Schritt 3: Binary statt JSON zurückgeben (optional)

Schritt 4: Verfügbare Image-Styles auflisten (optional)

Request-Parameter

Modellspezifische Optionen

Hochauflösende Generierung

LoRA-Stärke

Adult-Inhalte und Safe Mode

Style-Presets

Style-Referenzen

Teilweise Varianten-Ergebnisse

OpenAI-kompatibler Endpoint

Adult-Content-Unschärfe auf `/images/generations` steuern

Prompting-Tipps

Fehler

Verfügbare Modelle