**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` | GPT Image 2.5，含 Flare 與 Sunburst 變體；支援 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

請求主體格式錯誤或缺少必要參數

Idempotency-Key 已被用於不同的請求主體。

已達速率限制。請等待 `Retry-After` 標頭中指定的秒數後再重試。

依文字提示詞產生圖片，可選擇以參考圖片引導，並支援多種模型。

圖片生成

輸入

輸出

相關 API