**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 ขนาดที่ระบุชัดเจนจะมีลำดับความสำคัญเหนือคำใบ้ความละเอียดใน 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 แบบเนทีฟ ทำตาม prompt ได้แม่นยำ และรองรับภาพอ้างอิงสูงสุด 10 รูป |
| `flux_2_pro` | การสร้างภาพ FLUX คุณภาพสูงโดย Black Forest Labs |
| `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

URL ของรูปภาพที่ประมวลผลแล้ว

code

message

URL ของรูปภาพที่สร้างหรือประมวลผลแล้ว

image_urls

data

เนื้อหาคำขอมีรูปแบบไม่ถูกต้องหรือขาดพารามิเตอร์ที่จำเป็น

ไม่มี API key หรือ key ไม่ถูกต้องหรือถูกเพิกถอนแล้ว

ยอดคงเหลือในบัญชีไม่เพียงพอหรือการสมัครใช้งานหมดอายุแล้ว

บัญชีไม่มีสิทธิ์เข้าถึง endpoint นี้

ใช้ Idempotency-Key ซ้ำกับเนื้อหาคำขอที่ต่างออกไป

ถูกจำกัดอัตราการเรียกใช้ (rate limit) ให้รอตามจำนวนวินาทีในเฮดเดอร์ `Retry-After` ก่อนลองใหม่

เกิดข้อผิดพลาดที่ไม่คาดคิดบนเซิร์ฟเวอร์

สร้างรูปภาพจาก prompt ข้อความ โดยใช้ภาพอ้างอิงช่วยกำหนดทิศทางได้ (ไม่บังคับ) และมีหลายโมเดลให้เลือก

API ที่เกี่ยวข้อง