**Cost**: configured per generated image in `pricing.yaml` (multiplied by `n`).

Text-to-image generation. Produce one or more images from a natural-language prompt, optionally steered by reference images for style or composition. Synchronous; routes through whichever model you pick.

## What this API is for

The canonical "generate image from text" endpoint. Use it for hero art, marketing assets, agent-driven illustration, batched A/B variants. Reference images give you style/subject control without fine-tuning.

## Request

| Field | Required | Notes |
|---|---|---|
| `prompt` | yes | Text description of the image to generate. The most important field — be specific about subject, composition, lighting, and style. |
| `n` | no | Number of images to generate. Default `1`. **Credits are charged per generated image**, not per call. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`, e.g. `1024x1024`. Defaults vary by model. Common: `1024x1024`, `1536x1024`, `1024x1536`. |
| `model` | no | Model ID. Default `nano_banana_2`. Available: `nano_banana_2`, `nano_banana_pro`, `gpt_image_2_5`, `gpt_image`, `qwen_image_3_pro`, `hy_image_3_5`, `seedream_5_pro`, `seedream_5_flash`, `seedream_5`, `seedream_4_5`, `recraft_v4`, `flux_3`, `flux_2_pro`, `flux_2_max`, `ideogram_v4`. Each has its own aesthetic / strength — see the table below. |
| `quality` | no | For `gpt_image`, use `low`, `medium`, `high`, or `auto`. For `gpt_image_2_5` (including Flare and Sunburst), `xhigh` and `max` are also supported. Omitted quality or `auto` uses the medium billing bucket. For non-GPT models, this field may carry the resolution tier (for example `1K` or `2K`). |
| `background` | no | Background mode (model-dependent). For `gpt_image`: `transparent` / `opaque` / `auto`. |
| `reference_images` | no | Array of public image URLs to steer the generation. Most models accept up to a handful — semantics vary (style ref vs. subject ref). `flux_3` accepts up to 10 reference images. |

### Model cheat-sheet

| Model | Strength |
|---|---|
| `nano_banana_2` (default) | Fast, general-purpose, good prompt adherence. |
| `nano_banana_pro` | Higher fidelity at higher latency. |
| `gpt_image_2_5` | GPT Image 2.5 with Flare and Sunburst variants; supports low, medium, high, xhigh, max, and auto quality. |
| `gpt_image` | Best for text inside images and structured layouts. Supports `quality` and `background`. |
| `qwen_image_3_pro` | Detailed layouts, multilingual text rendering, dense information-rich images, and 512/1K/2K outputs. No 4K. `image_generate` accepts up to 3 references; `image_to_image` accepts up to 2. |
| `hy_image_3_5` | Photorealistic generation and reference-guided editing; 1K/2K outputs and up to 5 input images. |
| `seedream_5_pro` | Precision generation and editing with advanced visual reasoning; 1K/2K outputs and up to 10 references. |
| `seedream_5_flash` | Fast, low-cost generation and editing; 1K/2K outputs at one price and up to 10 references. |
| `seedream_5` / `seedream_4_5` | Cinematic, photographic. |
| `flux_3` | Native 1K/2K/4K generation, precise prompt following, and up to 10 references. |
| `flux_2_pro` / `flux_2_max` | High-quality, very precise prompt following. |
| `recraft_v4` | Vector-friendly art / illustration. |
| `ideogram_v4` | Latest Ideogram typography, posters, logos. |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` is an array of CDN URLs, length `n`.

## Billing

**Credits charged per generated image**, not per call. For `n = 4`, the configured per-image model price is multiplied by 4. Check `GET /v2/open/limits` for the live per-operation price table and `GET /v2/open/usage` for charged calls. Uses the unified Codia Open API balance.

## Errors

- `400` — missing/empty `prompt`, invalid `size` format, unknown `model`, too many `reference_images`.
- `401` / `403` — auth.
- `402` — credits exhausted.
- `429` — rate limit.
- `500` — internal; safe to retry.

> **Sync vs. async**
> This synchronous endpoint returns the result inline. When `n > 1` the call generates images concurrently and may still approach HTTP timeouts; prefer `POST /v2/open/tasks` with `operation=image_generate` for batch jobs (and for webhook delivery / retry semantics). Inputs and per-image credit cost are identical.

Clave opcional proporcionada por el usuario (hasta 255 caracteres). Si se indica, una respuesta correcta (2xx) se guarda en caché durante 7 días. Un reintento con la misma clave y un cuerpo de solicitud idéntico devuelve la respuesta en caché (sin cobrar créditos adicionales); un reintento con la misma clave pero un cuerpo distinto devuelve 409. Úsala para que reintentar un POST tras un fallo de red sea seguro.

Idempotency-Key

Descripción en texto de la imagen que se va a generar

prompt

Número de imágenes que se van a generar. Los créditos se cobran por cada imagen generada.

Dimensiones de la imagen de salida en formato `WIDTHxHEIGHT`. Tamaños habituales: `1024x1024`, `1536x1024`, `1024x1536`. FLUX 2 Pro/Max también aceptan los preajustes de tamaño 1K/2K. Las solicitudes demasiado grandes, incluidas las de 4K, se reducen a un máximo aproximado de 4MP (2048x2048 para imágenes cuadradas); no se admite la salida 4K nativa. La facturación usa el área de salida ajustada: hasta 1,048,576 píxeles en total se aplica el precio de 1K, y las salidas más grandes usan el precio de 2K. Un size explícito tiene prioridad sobre una indicación de resolución en quality.

size

Modelo que genera la imagen. El valor predeterminado es `nano_banana_2`. Los modelos admitidos coinciden con los de Codia Studio para la generación de texto a imagen. Los créditos se configuran en `pricing.yaml` y los devuelve `GET /v2/open/limits`.

| Modelo | Ideal para |
| --- | --- |
| `nano_banana_2` | Generación rápida para el día a día (Gemini 3.1 Flash). |
| `nano_banana_pro` | Visuales 4K con calidad de estudio y razonamiento avanzado (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 con las variantes Flare y Sunburst; admite las calidades low, medium, high, xhigh, max y auto. |
| `gpt_image` | Texto nítido dentro de la imagen, referencias de alta fidelidad y tamaños flexibles. Admite `quality` (`low`/`medium`/`high`/`auto`) y `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Layouts detallados, renderizado de texto multilingüe, imágenes con mucha información y salidas 512/1K/2K. Sin 4K. `image_generate` acepta hasta 3 referencias; `image_to_image`, hasta 2. |
| `hy_image_3_5` | Generación fotorrealista y edición guiada por referencias en 1K/2K. Sin 4K. Acepta hasta 5 imágenes de entrada por solicitud. |
| `seedream_5_pro` | Generación de precisión con razonamiento visual avanzado; admite salidas 1K/2K y hasta 10 imágenes de referencia. |
| `seedream_5_flash` | Generación rápida y económica; admite salidas 1K/2K al mismo precio y hasta 10 imágenes de referencia. |
| `seedream_5` | Imágenes fotorrealistas con gran nivel de detalle. Los tamaños se basan en 1920, p. ej., `1920x1080`. |
| `seedream_4_5` | Fotorrealismo fiable, ideal para retratos. Los tamaños se basan en 1920. |
| `recraft_v4` | Ilustraciones, iconos y arte de estilo vectorial con control preciso del estilo. |
| `flux_3` | Generación nativa en 1K/2K/4K con gran fidelidad al prompt y hasta 10 referencias. |
| `flux_2_pro` | Generación FLUX de alta calidad de Black Forest Labs. |
| `flux_2_max` | Nivel FLUX de máxima calidad para resultados premium. |
| `ideogram_v4` | La tipografía y las composiciones creativas más recientes de Ideogram. |

model

Para `gpt_image`, usa `low`, `medium`, `high` o `auto`. Para `gpt_image_2_5` (incluidos Flare y Sunburst), también se admiten `xhigh` y `max`. Si se omite quality o se usa `auto`, se aplica el tramo de facturación medium. En los modelos que no son GPT, este campo puede indicar el nivel de resolución (por ejemplo, `1K` o `2K`).

quality

Modo de fondo (depende del modelo). Para GPT Image 2 y 2.5: `transparent`, `opaque` o `auto`.

background

URL de imágenes de referencia para orientar el estilo (depende del modelo)

reference_images

code

message

URL de las imágenes generadas o procesadas

image_urls

data

El cuerpo de la solicitud tiene un formato incorrecto o le faltan parámetros obligatorios

Falta la clave de API, no es válida o se ha revocado

El saldo de la cuenta es insuficiente o la suscripción ha caducado

La cuenta no tiene acceso a este endpoint

Idempotency-Key reutilizada con un cuerpo de solicitud distinto.

Límite de frecuencia alcanzado. Espera el número de segundos indicado en el encabezado `Retry-After` antes de reintentar.

Se ha producido un error inesperado en el servidor

Genera imágenes a partir de un prompt de texto, opcionalmente guiadas por imágenes de referencia, con varios modelos a elegir.

Generar imagen

Entrada

Salida

APIs relacionadas