> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generación de imágenes
> Genera imágenes desde prompts con la API nativa de Venice o el endpoint compatible con OpenAI, con estilo y salida binaria o base64.
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:
```json theme={"system"}
{
"model": "nano-banana-pro",
"prompt": "A serene canal in Venice at sunset",
"aspect_ratio": "16:9",
"resolution": "2K"
}
```
Usa [Modelos de imagen](/models/image) o la [API de Models](/api-reference/endpoint/models/list) para confirmar qué campos de tamaño acepta cada modelo.
**Respuesta (200):**
```json theme={"system"}
{
"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
```python Python theme={"system"}
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']}")
```
```javascript Node.js theme={"system"}
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.
```bash theme={"system"}
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`:
```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**Respuesta (200):**
```json theme={"system"}
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
```
A continuación, pasa uno de esos valores en tu solicitud de generación:
```json theme={"system"}
{
"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](/api-reference/endpoint/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](/models/image) y la [API de Models](/api-reference/endpoint/models/list) 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:
```json theme={"system"}
{
"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`:
```json theme={"system"}
{
"model": "gpt-image-2",
"prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
"aspect_ratio": "16:9",
"resolution": "4K"
}
```
```json theme={"system"}
{
"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](/models/image) 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](/api-reference/endpoint/image/styles):
```json theme={"system"}
{
"model": "qwen-image-2",
"prompt": "A futuristic Venice skyline at sunrise",
"style_preset": "3D Model"
}
```
Consulta [Image Styles](/api-reference/endpoint/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:**
```json theme={"system"}
{
"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
1. Empieza con el sujeto, después añade medio, iluminación, composición y atmósfera.
2. Pon los detalles a evitar en `negative_prompt` en lugar de sobrecargar el prompt principal.
3. Reutiliza `seed` al iterar para que puedas comparar cambios de prompt sin cambiar completamente la composición.
4. 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`.
5. 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](https://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](/models/image) para la lista actual de modelos, precios y soporte de funciones.