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

生成する画像の枚数。クレジットは生成された画像 1 枚ごとに消費されます。

`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 には対応していません。1 リクエストあたり最大 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

生成または処理された画像の URL

image_urls

data

リクエストボディの形式が正しくないか、必須パラメータが不足しています

API キーが指定されていないか、無効か、失効しています

アカウントの残高が不足しているか、サブスクリプションの有効期限が切れています

アカウントにこのエンドポイントへのアクセス権がありません

Idempotency-Key が異なるリクエストボディで再利用されました。

レート制限に達しました。`Retry-After` ヘッダーに示された秒数だけ待ってからリトライしてください。

サーバーで予期しないエラーが発生しました

テキストプロンプトから画像を生成します。参照画像でガイドすることもでき、複数のモデルから選択できます。

関連する API