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

사용자가 지정하는 선택적 키(최대 255자). 설정하면 성공한(2xx) 응답이 7일 동안 캐시됩니다. 같은 키와 동일한 요청 본문으로 재시도하면 캐시된 응답이 반환되며 크레딧이 추가로 차감되지 않습니다. 같은 키로 다른 본문을 보내면 409가 반환됩니다. 네트워크 장애 시 POST를 안전하게 재시도할 수 있도록 하려면 이 키를 사용합니다.

Idempotency-Key

생성할 이미지에 대한 텍스트 설명

prompt

생성할 이미지 수. 크레딧은 생성된 이미지마다 차감됩니다.

`WIDTHxHEIGHT` 형식의 출력 이미지 크기. 일반적인 크기: `1024x1024`, `1536x1024`, `1024x1536`. FLUX 2 Pro/Max는 1K/2K 크기 프리셋도 허용합니다. 4K를 포함해 너무 큰 요청은 최대 약 4MP(정사각형 이미지의 경우 2048x2048)로 축소되며, 네이티브 4K 출력은 지원되지 않습니다. 과금은 조정된 출력 면적을 기준으로 하며, 총 1,048,576픽셀 이하는 1K 가격이, 그보다 큰 출력은 2K 가격이 적용됩니다. 명시적인 size는 quality에 포함된 해상도 힌트보다 우선합니다.

size

이미지를 생성하는 모델. 기본값은 `nano_banana_2`입니다. 지원 모델은 Codia Studio의 텍스트-이미지 생성과 동일합니다. 크레딧은 `pricing.yaml`에서 설정되며 `GET /v2/open/limits`로 확인할 수 있습니다.

| 모델 | 적합한 용도 |
| --- | --- |
| `nano_banana_2` | 일상적인 용도의 빠른 생성(Gemini 3.1 Flash). |
| `nano_banana_pro` | 고급 추론을 활용한 스튜디오 품질의 4K 비주얼(Gemini 3 Pro). |
| `gpt_image_2_5` | Flare 및 Sunburst 변형을 제공하는 GPT Image 2.5. low, medium, high, xhigh, max, auto 품질을 지원합니다. |
| `gpt_image` | 선명한 이미지 내 텍스트, 고충실도 참조, 유연한 크기. `quality`(`low`/`medium`/`high`/`auto`)와 `background`(`transparent`/`opaque`/`auto`)를 지원합니다. |
| `qwen_image_3_pro` | 정교한 레이아웃, 다국어 텍스트 렌더링, 정보 밀도가 높은 이미지, 512/1K/2K 출력. 4K는 지원하지 않습니다. 참조 이미지는 `image_generate`에서 최대 3개, `image_to_image`에서 최대 2개까지 허용됩니다. |
| `hy_image_3_5` | 1K/2K에서의 사실적인 생성과 참조 기반 편집. 4K는 지원하지 않습니다. 요청당 최대 5개의 입력 이미지를 허용합니다. |
| `seedream_5_pro` | 고급 시각 추론을 활용한 정밀 생성. 1K/2K 출력과 최대 10개의 참조 이미지를 지원합니다. |
| `seedream_5_flash` | 빠르고 저렴한 생성. 1K/2K 출력을 동일한 가격으로 제공하며 최대 10개의 참조 이미지를 지원합니다. |
| `seedream_5` | 세밀한 디테일의 사실적인 이미지. 크기는 1920 기준입니다(예: `1920x1080`). |
| `seedream_4_5` | 안정적인 사실적 표현으로 인물 사진에 적합합니다. 크기는 1920 기준입니다. |
| `recraft_v4` | 정밀한 스타일 제어가 가능한 일러스트, 아이콘, 벡터 스타일 아트. |
| `flux_3` | 네이티브 1K/2K/4K 생성. 프롬프트를 정확하게 따르며 최대 10개의 참조 이미지를 지원합니다. |
| `flux_2_pro` | Black Forest Labs의 고품질 FLUX 생성. |
| `flux_2_max` | 프리미엄 결과물을 위한 최고 품질의 FLUX 등급. |
| `ideogram_v4` | 최신 Ideogram 타이포그래피와 창의적인 구도. |

model

`gpt_image`에는 `low`, `medium`, `high`, `auto`를 사용합니다. `gpt_image_2_5`(Flare 및 Sunburst 포함)에서는 `xhigh`와 `max`도 지원됩니다. quality를 생략하거나 `auto`로 지정하면 medium 과금 구간이 적용됩니다. GPT가 아닌 모델에서는 이 필드에 해상도 등급(예: `1K` 또는 `2K`)이 들어갈 수 있습니다.

quality

배경 모드(모델에 따라 다름). GPT Image 2 및 2.5에서는 `transparent`, `opaque`, `auto`를 사용할 수 있습니다.

background

스타일 가이드용 참조 이미지 URL(모델에 따라 다름)

reference_images

code

message

image_urls

data

요청 본문의 형식이 잘못되었거나 필수 매개변수가 누락되었습니다

API 키가 없거나, 유효하지 않거나, 폐기되었습니다

계정 잔액이 부족하거나 구독이 만료되었습니다

계정에 이 엔드포인트에 대한 액세스 권한이 없습니다

Idempotency-Key가 다른 요청 본문과 함께 재사용되었습니다.

속도 제한에 도달했습니다. `Retry-After` 헤더에 표시된 초만큼 기다린 후 재시도하십시오.

서버에서 예기치 않은 오류가 발생했습니다

텍스트 프롬프트로 이미지를 생성합니다. 필요하면 참조 이미지로 결과를 유도할 수 있으며, 여러 모델 중에서 선택할 수 있습니다.

관련 API