**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.

Chave opcional fornecida pelo usuário (até 255 caracteres). Quando definida, uma resposta bem-sucedida (2xx) fica em cache por 7 dias. Uma nova tentativa com a mesma chave e o mesmo corpo de requisição retorna a resposta em cache (sem cobrança extra de créditos); uma nova tentativa com a mesma chave, mas com um corpo diferente, retorna 409. Use para que repetir um POST após falhas de rede seja seguro.

Idempotency-Key

Descrição em texto da imagem a ser gerada

prompt

Número de imagens a gerar. Os créditos são cobrados por imagem gerada.

Dimensões da imagem de saída no formato `WIDTHxHEIGHT`. Tamanhos comuns: `1024x1024`, `1536x1024`, `1024x1536`. FLUX 2 Pro/Max também aceitam os presets de tamanho 1K/2K. Requisições grandes demais, incluindo 4K, são reduzidas para no máximo cerca de 4MP (2048x2048 para imagens quadradas); a saída 4K nativa não é suportada. A cobrança usa a área de saída ajustada: até 1,048,576 pixels no total usa o preço de 1K, e saídas maiores usam o preço de 2K. Um size explícito tem prioridade sobre uma indicação de resolução em quality.

size

Modelo que gera a imagem. O padrão é `nano_banana_2`. Os modelos suportados são os mesmos do Codia Studio para geração de texto para imagem. Os créditos são configurados em `pricing.yaml` e retornados por `GET /v2/open/limits`.

| Modelo | Ideal para |
| --- | --- |
| `nano_banana_2` | Geração rápida para o dia a dia (Gemini 3.1 Flash). |
| `nano_banana_pro` | Visuais 4K com qualidade de estúdio e raciocínio avançado (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 com as variantes Flare e Sunburst; suporta as qualidades low, medium, high, xhigh, max e auto. |
| `gpt_image` | Texto nítido na imagem, referências de alta fidelidade e tamanhos flexíveis. Suporta `quality` (`low`/`medium`/`high`/`auto`) e `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Layouts detalhados, renderização de texto multilíngue, imagens densas em informação e saídas 512/1K/2K. Sem 4K. `image_generate` aceita até 3 referências; `image_to_image` aceita até 2. |
| `hy_image_3_5` | Geração fotorrealista e edição guiada por referências em 1K/2K. Sem 4K. Aceita até 5 imagens de entrada por requisição. |
| `seedream_5_pro` | Geração de precisão com raciocínio visual avançado; suporta saídas 1K/2K e até 10 imagens de referência. |
| `seedream_5_flash` | Geração rápida e de baixo custo; suporta saídas 1K/2K pelo mesmo preço e até 10 imagens de referência. |
| `seedream_5` | Imagens fotorrealistas com detalhes finos. Os tamanhos têm base 1920, por exemplo `1920x1080`. |
| `seedream_4_5` | Fotorrealismo confiável, ótimo para retratos. Os tamanhos têm base 1920. |
| `recraft_v4` | Ilustrações, ícones e arte em estilo vetorial com controle preciso de estilo. |
| `flux_3` | Geração nativa em 1K/2K/4K com alta fidelidade ao prompt e até 10 referências. |
| `flux_2_pro` | Geração FLUX de alta qualidade da Black Forest Labs. |
| `flux_2_max` | Nível FLUX de qualidade máxima para resultados premium. |
| `ideogram_v4` | A tipografia e as composições criativas mais recentes da Ideogram. |

model

Para `gpt_image`, use `low`, `medium`, `high` ou `auto`. Para `gpt_image_2_5` (incluindo Flare e Sunburst), `xhigh` e `max` também são suportados. Se quality for omitido ou `auto`, é usada a faixa de cobrança medium. Para modelos não GPT, este campo pode indicar a faixa de resolução (por exemplo, `1K` ou `2K`).

quality

Modo de fundo (depende do modelo). Para GPT Image 2 e 2.5: `transparent`, `opaque` ou `auto`.

background

URLs de imagens de referência para orientar o estilo (depende do modelo)

reference_images

code

message

image_urls

data

O corpo da requisição está malformado ou faltam parâmetros obrigatórios

A chave de API está ausente, é inválida ou foi revogada

O saldo da conta é insuficiente ou a assinatura expirou

Idempotency-Key reutilizada com um corpo de requisição diferente.

Limite de taxa atingido. Aguarde o número de segundos indicado no cabeçalho `Retry-After` antes de tentar novamente.

Gera imagens a partir de um prompt de texto, opcionalmente guiadas por imagens de referência, com vários modelos à escolha.

Gerar imagem

Entrada

Saída

APIs relacionadas