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

Clé facultative fournie par l’utilisateur (jusqu’à 255 caractères). Si elle est définie, une réponse réussie (2xx) est mise en cache pendant 7 jours. Une nouvelle tentative avec la même clé et un corps de requête identique renvoie la réponse en cache (sans crédit supplémentaire facturé) ; une nouvelle tentative avec la même clé mais un corps différent renvoie 409. Permet de relancer un POST sans risque en cas d’erreur réseau.

Idempotency-Key

Description textuelle de l’image à générer

prompt

Nombre d’images à générer. Les crédits sont facturés par image générée.

Dimensions de l’image de sortie au format `WIDTHxHEIGHT`. Tailles courantes : `1024x1024`, `1536x1024`, `1024x1536`. FLUX 2 Pro/Max acceptent aussi les préréglages de taille 1K/2K. Les requêtes surdimensionnées, 4K compris, sont réduites à environ 4MP au maximum (2048x2048 pour une image carrée) ; la sortie 4K native n’est pas prise en charge. La facturation se base sur la surface de sortie ajustée : jusqu’à 1,048,576 pixels au total, le prix 1K s’applique ; au-delà, c’est le prix 2K. Une valeur size explicite prime sur une indication de résolution dans quality.

size

Modèle qui génère l’image. Par défaut : `nano_banana_2`. Les modèles pris en charge sont les mêmes que dans Codia Studio pour la génération texte-image. Les crédits sont configurés dans `pricing.yaml` et renvoyés par `GET /v2/open/limits`.

| Modèle | Idéal pour |
| --- | --- |
| `nano_banana_2` | Génération rapide pour un usage quotidien (Gemini 3.1 Flash). |
| `nano_banana_pro` | Visuels 4K de qualité studio avec raisonnement avancé (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 avec les variantes Flare et Sunburst ; prend en charge les qualités low, medium, high, xhigh, max et auto. |
| `gpt_image` | Texte net dans l’image, références haute fidélité, tailles flexibles. Prend en charge `quality` (`low`/`medium`/`high`/`auto`) et `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Mises en page détaillées, rendu de texte multilingue, images denses et riches en informations, sorties 512/1K/2K. Pas de 4K. `image_generate` accepte jusqu’à 3 références ; `image_to_image` jusqu’à 2. |
| `hy_image_3_5` | Génération photoréaliste et retouche guidée par référence en 1K/2K. Pas de 4K. Accepte jusqu’à 5 images d’entrée par requête. |
| `seedream_5_pro` | Génération de précision avec raisonnement visuel avancé ; prend en charge les sorties 1K/2K et jusqu’à 10 images de référence. |
| `seedream_5_flash` | Génération rapide et économique ; prend en charge les sorties 1K/2K au même prix et jusqu’à 10 images de référence. |
| `seedream_5` | Images photoréalistes aux détails fins. Tailles basées sur 1920, par ex. `1920x1080`. |
| `seedream_4_5` | Photoréalisme fiable, idéal pour les portraits. Tailles basées sur 1920. |
| `recraft_v4` | Illustrations, icônes et visuels de style vectoriel avec un contrôle précis du style. |
| `flux_3` | Génération native 1K/2K/4K, avec un respect précis du prompt et jusqu’à 10 références. |
| `flux_2_pro` | Génération FLUX de haute qualité, par Black Forest Labs. |
| `flux_2_max` | Niveau FLUX de qualité maximale pour des résultats premium. |
| `ideogram_v4` | Dernière version d’Ideogram pour la typographie et les compositions créatives. |

model

Pour `gpt_image`, utilisez `low`, `medium`, `high` ou `auto`. Pour `gpt_image_2_5` (y compris Flare et Sunburst), `xhigh` et `max` sont également pris en charge. Si quality est omis ou vaut `auto`, le palier de facturation medium s’applique. Pour les modèles non GPT, ce champ peut contenir le palier de résolution (par exemple `1K` ou `2K`).

quality

Mode d’arrière-plan (selon le modèle). Pour GPT Image 2 et 2.5 : `transparent`, `opaque` ou `auto`.

background

URL d’images de référence pour guider le style (selon le modèle)

reference_images

code

message

image_urls

data

Le corps de la requête est mal formé ou des paramètres obligatoires sont manquants

La clé d’API est manquante, invalide ou révoquée

Le solde du compte est insuffisant ou l’abonnement a expiré

Le compte n’a pas accès à cet endpoint

Idempotency-Key réutilisée avec un corps de requête différent.

Limite de débit atteinte. Attendez le nombre de secondes indiqué dans l’en-tête `Retry-After` avant de réessayer.

Une erreur inattendue s’est produite sur le serveur

Génère des images à partir d’un prompt textuel, éventuellement guidé par des images de référence, avec plusieurs modèles au choix.

Générer une image

Entrée

Sortie

APIs associées