> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-f533effe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Generación de imágenes
> Genera imágenes desde prompts de texto con la API de Venice, cubriendo opciones de tamaño por modelo, presets de estilo, intensidad de LoRA, modo seguro y salida binaria.
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 |
| `lora_strength` | integer | No | - | Intensidad (`0`-`100`) de los LoRAs integrados en el modelo; los modelos sin LoRAs adicionales lo ignoran |
| `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.
### Soporte de LoRA
Algunos modelos de imagen incluyen LoRAs adicionales integrados. El parámetro `lora_strength` (integer, `0` a `100`) controla con qué intensidad se aplican esos LoRAs integrados. Solo afecta a los modelos que usan LoRAs adicionales. Los demás modelos lo ignoran.
La API no admite subir ni cargar archivos de LoRA personalizados. Tampoco hay un endpoint que liste los LoRAs incluidos con un modelo. El uso de LoRA se limita a ajustar `lora_strength` en los modelos que los incluyen.
### 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`. Establécelo en `false` si tu caso de uso permite contenido adulto y quieres la salida sin filtrar:
```json theme={"system"}
{
"model": "lustify-v8",
"prompt": "…",
"safe_mode": false
}
```
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](/models/image) y [Precios](/overview/pricing) para ver la lista actual y los costes por modelo.
Para editar imágenes existentes, el modelo de edición predeterminado `qwen-edit` bloquea la imaginería sexual explícita. Si necesitas edición sin censura, usa `qwen-edit-uncensored` a través de [Edición de imágenes](/guides/media/image-editing).
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.
### 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.
### 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) | Habilita el modo Safe Venice y difumina el contenido adulto |
| `low` | Deshabilita el modo Safe Venice; devuelve la salida sin difuminar |
```json theme={"system"}
{
"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`.
***
## 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?utm_source=venice-api-documentation) |
| `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.