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. 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']}")

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 \
  -H "Authorization: Bearer $VENICE_API_KEY"

Respuesta (200):

[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]

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` y `qwen-image`
`height`	integer	No	`1024`	Alto de salida en píxeles para modelos basados en píxeles como `venice-sd35` y `qwen-image`
`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`
`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
`style_preset`	string	No	-	Aplica un estilo preset de Image Styles
`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

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.

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.

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": "qwen-image-2",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

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, variants o respuestas binarias.

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
`415`	Tipo de contenido no válido	Envía JSON con `Content-Type: application/json`
`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 Venice está activado, 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.

​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

​Presets de estilo

​Endpoint compatible con OpenAI

​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

Presets de estilo

Endpoint compatible con OpenAI

Consejos para prompting

Errores

Modelos disponibles