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

Kunci opsional dari pengguna (maksimal 255 karakter). Jika diisi, respons sukses (2xx) di-cache selama 7 hari. Retry dengan kunci yang sama + body permintaan yang identik mengembalikan respons dari cache (tanpa potongan kredit tambahan); retry dengan kunci yang sama tetapi body berbeda mengembalikan 409. Gunakan agar POST aman di-retry saat terjadi gangguan jaringan.

Idempotency-Key

Deskripsi teks gambar yang akan dihasilkan

prompt

Jumlah gambar yang akan dihasilkan. Kredit dipotong per gambar yang dihasilkan.

Dimensi gambar output dalam format `WIDTHxHEIGHT`. Ukuran umum: `1024x1024`, `1536x1024`, `1024x1536`. FLUX 2 Pro/Max juga menerima preset ukuran 1K/2K. Permintaan yang terlalu besar, termasuk 4K, diperkecil menjadi maksimal sekitar 4MP (2048x2048 untuk gambar persegi); output 4K native tidak didukung. Penagihan memakai luas output setelah penyesuaian: total hingga 1,048,576 piksel memakai harga 1K, dan output yang lebih besar memakai harga 2K. Ukuran yang ditentukan secara eksplisit lebih diutamakan daripada petunjuk resolusi di quality.

size

Model yang menghasilkan gambar. Default-nya `nano_banana_2`. Model yang didukung sama dengan Codia Studio untuk pembuatan text-to-image. Kredit dikonfigurasi di `pricing.yaml` dan dikembalikan oleh `GET /v2/open/limits`.

| Model | Cocok untuk |
| --- | --- |
| `nano_banana_2` | Pembuatan gambar sehari-hari yang cepat (Gemini 3.1 Flash). |
| `nano_banana_pro` | Visual 4K berkualitas studio dengan penalaran tingkat lanjut (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 dengan varian Flare dan Sunburst; mendukung kualitas low, medium, high, xhigh, max, dan auto. |
| `gpt_image` | Teks dalam gambar yang tajam, referensi presisi tinggi, ukuran fleksibel. Mendukung `quality` (`low`/`medium`/`high`/`auto`) dan `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Layout detail, rendering teks multibahasa, gambar padat informasi, dan output 512/1K/2K. Tanpa 4K. `image_generate` menerima hingga 3 referensi; `image_to_image` menerima hingga 2. |
| `hy_image_3_5` | Pembuatan gambar fotorealistis dan pengeditan berbasis referensi pada 1K/2K. Tanpa 4K. Menerima hingga 5 gambar input per permintaan. |
| `seedream_5_pro` | Pembuatan gambar presisi dengan penalaran visual tingkat lanjut; mendukung output 1K/2K dan hingga 10 gambar referensi. |
| `seedream_5_flash` | Pembuatan gambar cepat dan hemat biaya; mendukung output 1K/2K dengan satu harga dan hingga 10 gambar referensi. |
| `seedream_5` | Gambar fotorealistis dengan detail halus. Ukuran berbasis 1920, misalnya `1920x1080`. |
| `seedream_4_5` | Fotorealisme yang andal, sangat baik untuk potret. Ukuran berbasis 1920. |
| `recraft_v4` | Ilustrasi, ikon, dan seni bergaya vektor dengan kontrol gaya yang presisi. |
| `flux_3` | Pembuatan gambar native 1K/2K/4K dengan kepatuhan prompt yang presisi dan hingga 10 referensi. |
| `flux_2_pro` | Pembuatan gambar FLUX berkualitas tinggi oleh Black Forest Labs. |
| `flux_2_max` | Tingkat FLUX dengan kualitas maksimum untuk hasil premium. |
| `ideogram_v4` | Tipografi dan komposisi kreatif Ideogram terbaru. |

model

Untuk `gpt_image`, gunakan `low`, `medium`, `high`, atau `auto`. Untuk `gpt_image_2_5` (termasuk Flare dan Sunburst), `xhigh` dan `max` juga didukung. Jika quality tidak diisi atau bernilai `auto`, dipakai tarif medium. Untuk model non-GPT, field ini dapat berisi tingkat resolusi (misalnya `1K` atau `2K`).

quality

Mode latar belakang (bergantung pada model). Untuk GPT Image 2 dan 2.5: `transparent`, `opaque`, atau `auto`.

background

URL gambar referensi untuk panduan gaya (bergantung pada model)

reference_images

code

message

image_urls

data

Body permintaan tidak valid atau parameter wajib tidak ada

API key tidak ada, tidak valid, atau sudah dicabut

Saldo akun tidak mencukupi atau langganan telah berakhir

Akun tidak memiliki akses ke endpoint ini

Idempotency-Key dipakai ulang dengan body permintaan yang berbeda.

Terkena rate limit. Tunggu selama jumlah detik di header `Retry-After` sebelum mencoba lagi.

Menghasilkan gambar dari prompt teks, opsional dipandu gambar referensi, dengan beragam pilihan model.

Buat Gambar

Input

Output

API terkait