Image Generation | Venice API Docs

La generación de imágenes en Venice es síncrona. Envía un prompt a /image/generate y recibe tu imagen en la misma respuesta, ya sea como base64 dentro de JSON o como binario en bruto cuando return_binary es true.

Endpoints

Endpoint	Propósito	Cuándo usarlo
`POST /image/generate`	API nativa de generación de imagen de Venice	Úsala para soporte completo de funciones
`GET /image/styles`	Lista los presets de estilo disponibles	Úsalo antes de enviar `style_preset`
`POST /images/generations`	API de generación de imagen compatible con OpenAI	Úsala al migrar clientes existentes de imagen de OpenAI

Paso 1: envía una solicitud de generación

El tamaño es específico de cada modelo. Algunos modelos aceptan width y height explícitos; otros exponen aspect_ratio; y los modelos con niveles de resolución exponen aspect_ratio más valores resolution como 1K, 2K o 4K.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo y qwen-image-2-1-pro ya no aceptan width ni height. Enviar cualquiera de los dos devuelve 400 con “width and height are no longer supported for this model. Use aspect_ratio instead.” Comprueba model_spec.constraints en GET /models?type=image antes de elegir los campos de tamaño.

Ejemplo basado en píxeles:

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

Ejemplo basado en aspect ratio:

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

Ejemplo con nivel de resolución:

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

El mismo patrón se aplica a otros modelos con niveles de resolución:

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

Usa Modelos de imagen o la API de Models para confirmar qué campos de tamaño acepta cada modelo. Respuesta (200):

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

El array images contiene los datos de imagen codificados en base64. Decodifica el primer elemento para guardarlo o mostrarlo. timing.total es la duración total de la solicitud en milisegundos.

Paso 2: decodifica y guarda la imagen

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}`);

Paso 3: devuelve binario en lugar de JSON (opcional)

Si quieres que el cuerpo de la respuesta sea el propio archivo de imagen, establece return_binary: true. Esto es útil cuando quieres transmitir o guardar la imagen directamente sin decodificar base64.

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

Cuando return_binary es true, el cuerpo de la respuesta son datos en bruto image/jpeg, image/png o image/webp según el format solicitado.

variants solo se admite cuando return_binary es false.

Paso 4: lista los estilos de imagen disponibles (opcional)

Si quieres usar style_preset, primero obtén los estilos disponibles desde /image/styles:

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

Este endpoint es público y no requiere una API key. Respuesta (200):

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

Los nombres de los estilos están dentro de data, no en el nivel superior: lee response.data en lugar de iterar directamente el objeto de la respuesta. A continuación, pasa uno de esos valores en tu solicitud de generación:

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

Usa el endpoint de estilos cuando quieras nombres exactos de presets en lugar de adivinarlos.

Parámetros de la solicitud

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`model`	string	Sí	-	ID del modelo a usar para la generación
`prompt`	string	Sí	-	Qué generar
`negative_prompt`	string	No	-	Qué evitar en la imagen
`width`	integer	No	`1024`	Ancho de salida en píxeles para modelos basados en píxeles como `venice-sd35`. Rechazado por la familia Qwen Image — consulta la nota más abajo
`height`	integer	No	`1024`	Alto de salida en píxeles para modelos basados en píxeles como `venice-sd35`. Rechazado por la familia Qwen Image — consulta la nota más abajo
`format`	string	No	`webp`	Formato de salida: `jpeg`, `png` o `webp`
`variants`	integer	No	`1`	Número de imágenes a generar (`1`-`4`), solo cuando `return_binary` es `false`. Un rechazo explícito por la política de contenido del proveedor puede omitir variantes individuales; consulta Resultados parciales de variantes
`return_binary`	boolean	No	`false`	Devuelve bytes de imagen en bruto en lugar de JSON con base64
`safe_mode`	boolean	No	`true`	Difumina contenido para adultos cuando está habilitado
`seed`	integer	No	aleatorio	Reutiliza la misma seed para iteraciones más consistentes
`cfg_scale`	number	No	depende del modelo	Valores más altos hacen que el modelo siga el prompt más estrictamente
`lora_strength`	integer	No	-	Intensidad (`0`-`100`) de los LoRA adicionales que usa un modelo. Consulta Intensidad de LoRA
`style_preset`	string	No	-	Aplica un estilo preset de Image Styles
`style_references`	array	No	-	Imágenes de referencia de estilo que guían la estética de la salida. Cada entrada es `{ "image": <url or base64>, "strength": <0.1-1> }`. Solo en modelos compatibles; consulta Referencias de estilo
`aspect_ratio`	string	Condicional	-	Usado por modelos que admiten tamaño basado en ratio, como `qwen-image-2`, `gpt-image-2`, `nano-banana-2` y `nano-banana-pro`
`resolution`	string	Condicional	-	Usado por modelos que admiten niveles de resolución como `1K`, `2K` o `4K`
`enable_web_search`	boolean	Condicional	`false`	Permite a los modelos admitidos usar información actual de la web; añade coste extra
`transparent_background`	boolean	No	`false`	Devuelve un PNG o WebP con un canal alfa real. Requiere un modelo con `supportsTransparentBackground: true` y `format` `png` o `webp`. Consulta Imágenes con fondo transparente

La validación es específica del modelo. Consulta Modelos de imagen y la API de Models antes de confiar en un parámetro entre varios modelos.

Opciones específicas del modelo

Generación de alta resolución

Algunos modelos de imagen admiten aspect_ratio sin un nivel resolution seleccionable. Por ejemplo, qwen-image-2 acepta aspect ratio y lo mapea a dimensiones de salida específicas del modelo:

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

Otros modelos de imagen admiten aspect_ratio más un nivel resolution. Por ejemplo, gpt-image-2, nano-banana-2 y nano-banana-pro admiten 1K, 2K y 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"
}

Usa Modelos de imagen para ver qué modelos admiten resoluciones más altas y cómo se cobran.

Intensidad de LoRA

Algunos modelos de imagen aplican LoRA adicionales. lora_strength (integer, de 0 a 100) define con qué intensidad se aplican y solo afecta a los modelos que los usan. La API no acepta archivos LoRA personalizados y ningún endpoint lista los LoRA que usa un modelo. lora_strength es el único control de LoRA.

Contenido adulto y modo seguro

safe_mode controla si el contenido adulto en la salida de generación se difumina. Su valor predeterminado es true, por lo que las imágenes clasificadas como adultas se devuelven difuminadas a menos que envíes safe_mode: false:

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

Las imágenes para adultos (NSFW) sin difuminar están disponibles para todos los usuarios de la API. No necesitas una suscripción Pro, y la configuración del filtro de contenido maduro en la app de Venice no afecta a las solicitudes de imágenes realizadas a través de la API. Algunos modelos de imagen están diseñados específicamente para generación adulta / sin censura y se combinan bien con safe_mode: false. Ejemplos en la página de precios incluyen lustify-sdxl, lustify-v7 y lustify-v8. Consulta Modelos de imagen y Precios para ver la lista actual y los costes por modelo. Para editar imágenes existentes, el modelo de edición predeterminado es firered-image-edit. Las políticas de contenido varían según el modelo de edición; si necesitas edición sin censura, usa qwen-edit-uncensored a través de Edición de imágenes. Cuando safe_mode está activado y el modelo devuelve una salida difuminada o moderada, inspecciona las cabeceras de respuesta x-venice-is-blurred y x-venice-is-content-violation si necesitas detectarlo de forma programática.

¿Usas una app de terceros? Las imágenes para adultos siguen difuminadas a menos que la app envíe safe_mode: false, o moderation: "low" en el endpoint compatible con OpenAI (ver más abajo).

Presets de estilo

Si el modelo seleccionado lo admite, style_preset te permite dirigir la salida sin reescribir todo el prompt. Puedes obtener los nombres válidos de preset desde Image Styles:

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

Consulta Image Styles para ver la lista de estilos actual.

Referencias de estilo

style_references va un paso más allá que style_preset: en lugar de un preset con nombre, condiciona la generación a una o más imágenes de referencia. Cada entrada tiene una image y un strength opcional:

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

Campo	Tipo	Obligatorio	Descripción
`image`	string	Sí	Imagen de referencia como URL `http://` o `https://`, cadena base64 o data URI en base64. Debe ser una imagen rasterizada (JPEG, PNG, WebP, HEIF, HEIC o AVIF), no puede ser SVG y debe pesar menos de 8 MB
`strength`	number	No	Con qué intensidad guía la referencia la salida, de `0.1` a `1`. Por defecto es `0.5`. Se ignora en los modelos donde `supportsStyleReferenceStrength` es `false`

La compatibilidad depende de cada modelo. Consulta GET /models?type=image:

model_spec.supportsStyleReferences es true solo en los modelos que aceptan el campo.
model_spec.constraints.maxStyleReferences es el número de entradas que acepta el modelo.
model_spec.constraints.supportsStyleReferenceStrength indica si strength tiene algún efecto.

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)"'

Enviar style_references a un modelo sin compatibilidad devuelve 400, igual que superar el límite de ese modelo o enviar una referencia corrupta, inaccesible o demasiado grande. Algunos modelos cobran una tarifa por referencia de estilo por cada imagen devuelta, además del precio base de la imagen; por ejemplo, Krea v2 Large y Krea v2 Medium. La tarifa solo se cobra por las imágenes que realmente se devuelven. Consulta Image Models para ver los precios base por imagen.

Resultados parciales de variantes

Con variants mayor que 1, la política de contenido del proveedor puede rechazar variantes individuales mientras el resto se generan correctamente. En ese caso, el endpoint sigue devolviendo 200 con menos imágenes de las que solicitaste:

Cuando se omiten una o más variantes, el cuerpo JSON incluye content_policy_violation_count, el número de variantes omitidas.
La cabecera de respuesta x-venice-content-violation-count contiene el mismo recuento.
x-venice-is-content-violation y x-venice-is-blurred describen las imágenes que se devolvieron.

Si se rechazan todas las variantes solicitadas, no se devuelve ninguna imagen y la solicitud falla con 422. No supongas que len(images) == variants; compara la longitud del array con variants y, cuando esté presente, comprueba content_policy_violation_count.

Endpoint compatible con OpenAI

Si ya estás usando los SDK de imagen de OpenAI o integraciones existentes de DALL-E, Venice también admite POST /images/generations. Ofrece un formato de solicitud más simple, pero menos funciones que el endpoint nativo de Venice. Solicitud:

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

size solo se aplica a los modelos con tamaño en píxeles, que tienen un widthHeightDivisor mayor que 1 en model_spec.constraints de GET /models?type=image. La mayoría de los modelos, incluido qwen-image-2, determinan el tamaño de la salida por relación de aspecto y resolución, e ignoran size. Algunos parámetros de OpenAI se aceptan por compatibilidad con los SDK, pero se ignoran (n está restringido a 1):

Parámetro	Comportamiento en `/images/generations`
`quality`	Se acepta y se ignora. La facturación usa el nivel de calidad predeterminado del modelo
`style`	Se acepta y se ignora
`output_compression`	Se acepta y se ignora
`user`	Se acepta, se descarta y no es un alias de `anon_user_id`
`n`	Solo se admite `1`; la validación rechaza otros valores

El control de niveles no existe en esta ruta: no hay campo resolution ni aspect_ratio, y quality no puede subir ni bajar el cargo. Para los modelos GPT Image con niveles, usa el endpoint nativo /image/generate cuando necesites elegir quality, resolution o aspect_ratio. Usa la ruta compatible con OpenAI para migraciones más rápidas. Usa /image/generate cuando necesites opciones específicas de Venice como cfg_scale, style_preset, style_references, variants o respuestas binarias.

Control del desenfoque de contenido adulto en `/images/generations`

El endpoint compatible con OpenAI no acepta safe_mode. Enviarlo devuelve un 400 con Unrecognized key(s) in object: 'safe_mode'. Usa en su lugar el parámetro moderation al estilo de OpenAI:

Valor	Comportamiento
`auto` (predeterminado)	Difumina el contenido adulto, igual que `safe_mode: true`
`low`	Devuelve la salida sin difuminar, igual que `safe_mode: false`

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

safe_mode solo funciona en el endpoint nativo POST /image/generate. moderation solo funciona en el endpoint compatible con OpenAI POST /images/generations. La misma división se aplica a la transparencia: /image/generate usa transparent_background: true, mientras que /images/generations usa el parámetro al estilo de OpenAI background: "transparent". Ambos requieren un formato de salida png o webp y un modelo con supportsTransparentBackground: true. Consulta Imágenes con fondo transparente.

Consejos para prompting

Empieza con el sujeto, después añade medio, iluminación, composición y atmósfera.
Pon los detalles a evitar en negative_prompt en lugar de sobrecargar el prompt principal.
Reutiliza seed al iterar para que puedas comparar cambios de prompt sin cambiar completamente la composición.
Mantén el tamaño consciente del modelo. Algunos modelos usan width/height, algunos usan aspect_ratio y los modelos con niveles de resolución usan aspect_ratio más resolution.
Usa variants durante la exploración y vuelve a una sola salida una vez que hayas fijado la dirección.

Errores

Estado	Significado	Acción
`400`	Parámetros de solicitud no válidos	Comprueba nombres de campo, tipos y restricciones específicas del modelo
`401`	Autenticación fallida o el modelo requiere un nivel de acceso mayor	Comprueba tu API key y el acceso al modelo
`402`	Saldo insuficiente	Añade créditos en venice.ai/settings/api
`404`	Modelo desconocido	Comprueba el ID del modelo con `GET /models?type=image`
`415`	Tipo de contenido no válido	Envía JSON con `Content-Type: application/json`
`422`	Infracción de la política de contenido	El proveedor rechazó explícitamente el prompt o la imagen. Ajusta el prompt o cambia de modelo. El cuerpo incluye `error` y un booleano `retryable`, y también puede incluir `suggested_prompt` y `recommended_model`
`429`	Límite de velocidad excedido o modelo sobrecargado	Reintenta con backoff; comprueba la cabecera `Retry-After`
`500`	Procesamiento de inferencia fallido	Reintenta la solicitud
`503`	Modelo a capacidad máxima	Reintenta tras una breve demora

Cuando safe_mode está activado (o moderation es auto), inspecciona cabeceras de respuesta como x-venice-is-blurred y x-venice-is-content-violation si necesitas detectar los resultados de moderación de forma programática.

Modelos disponibles

Consulta Modelos de imagen para la lista actual de modelos, precios y soporte de funciones.

Documentación

Primeros pasos

Texto y chat

Imagen

Vídeo

Audio

Búsqueda y RAG

Agentes e integraciones

Herramientas de código

Herramientas para agentes

SDK y frameworks

Generación de imágenes

Endpoints

Paso 1: envía una solicitud de generación

Paso 2: decodifica y guarda la imagen

Paso 3: devuelve binario en lugar de JSON (opcional)

Paso 4: lista los estilos de imagen disponibles (opcional)

Parámetros de la solicitud

Opciones específicas del modelo

Generación de alta resolución

Intensidad de LoRA

Contenido adulto y modo seguro

Presets de estilo

Referencias de estilo

Resultados parciales de variantes

Endpoint compatible con OpenAI

Control del desenfoque de contenido adulto en `/images/generations`

Consejos para prompting

Errores

Modelos disponibles

​Endpoints

​Paso 1: envía una solicitud de generación

​Paso 2: decodifica y guarda la imagen

​Paso 3: devuelve binario en lugar de JSON (opcional)

​Paso 4: lista los estilos de imagen disponibles (opcional)

​Parámetros de la solicitud

​Opciones específicas del modelo

​Generación de alta resolución

​Intensidad de LoRA

​Contenido adulto y modo seguro

​Presets de estilo

​Referencias de estilo

​Resultados parciales de variantes

​Endpoint compatible con OpenAI

​Control del desenfoque de contenido adulto en /images/generations

​Consejos para prompting

​Errores

​Modelos disponibles

Endpoints

Paso 1: envía una solicitud de generación

Paso 2: decodifica y guarda la imagen

Paso 3: devuelve binario en lugar de JSON (opcional)

Paso 4: lista los estilos de imagen disponibles (opcional)

Parámetros de la solicitud

Opciones específicas del modelo

Generación de alta resolución

Intensidad de LoRA

Contenido adulto y modo seguro

Presets de estilo

Referencias de estilo

Resultados parciales de variantes

Endpoint compatible con OpenAI

Control del desenfoque de contenido adulto en `/images/generations`

Consejos para prompting

Errores

Modelos disponibles