**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 مفقود أو غير صالح أو تم إبطاله

رصيد الحساب غير كافٍ أو انتهت صلاحية الاشتراك

لا يملك الحساب صلاحية الوصول إلى نقطة النهاية هذه

أُعيد استخدام Idempotency-Key مع جسم طلب مختلف.

تم تجاوز حد المعدل. انتظر عدد الثواني المحدد في الترويسة `Retry-After` قبل إعادة المحاولة.

حدث خطأ غير متوقع في الخادم

يولّد صورًا من prompt نصي، مع إمكانية الاسترشاد بصور مرجعية اختياريًا، مع مجموعة من النماذج للاختيار بينها.

إنشاء صورة

المدخلات

المخرجات

واجهات API ذات صلة