**Cost**: configured in `pricing.yaml` (model-dependent — see `model` field).

Image to Image supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/image/image_to_image' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'prompt=make it watercolor'
```

Transform a source image into a new one steered by a text prompt — "this photo, but Studio Ghibli style", "this product shot, but at sunset", "this sketch, refined into a finished painting". Synchronous. Different from `remix` (which preserves more structure) and `replace_background` (which only changes the background).

## What this API is for

Style transfer, refinement, restylization, scene editing — any task framed as "take this image and change it according to this instruction". Holds onto the source's overall composition more loosely than `remix` — use that one when you need tighter structural preservation.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `prompt` | yes | Text description of the desired transformation. |
| `model` | no | Default `nano_banana_2`. Same model menu as `generate_image`: `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`. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`. For GPT Image 2 and 2.5, size is normalized into the pricing resolution bucket (`1K`, `2K`, `4K`). |
| `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 | GPT Image only: `transparent`, `opaque`, or `auto`. Ignored by non-GPT models. |
| `reference_images` | no | Additional public image URLs for style or subject guidance. For `qwen_image_3_pro`, `image_to_image` accepts up to 2 `reference_images`. For `flux_3`, the source image plus additional references may total up to 10 images. |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one URL of the transformed image.

## Billing & limits

- Credits come from `pricing.yaml` for the selected model. For GPT Image 2 and 2.5, the billing key combines resolution and quality, e.g. `1K_high`; call `GET /v2/open/limits` for live values.
- Synchronous, single-call.

## When to pick what

- Want a complete transformation? → `image_to_image`.
- Want to keep structure but change style? → `remix`.
- Want to keep subject and only change scene? → `replace_background`.
- Want to start from scratch with optional refs? → `generate_image`.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_to_image` instead. Inputs and credit cost are identical.

مفتاح اختياري يحدده المستخدم (حتى 255 حرفًا). عند تعيينه، تُخزَّن الاستجابة الناجحة (2xx) مؤقتًا لمدة 7 أيام. إعادة المحاولة بالمفتاح نفسه + جسم طلب مطابق تُعيد الاستجابة المخزّنة (دون خصم رصيد إضافي)؛ أما إعادة المحاولة بالمفتاح نفسه مع جسم مختلف فتُعيد 409. استخدمه لجعل إعادة إرسال POST آمنة عند حدوث أعطال في الشبكة. في عمليات الرفع بصيغة multipart/form-data، تُقارن الطلبات بحسب حقول النموذج ومحتوى الملفات، لذا يُعاد تشغيل الرفع المُكرَّر حتى لو اختار العميل multipart boundary جديدًا.

Idempotency-Key

رابط URL العام للصورة المصدر المراد تحويلها

image_url

وصف نصي للتحويل المطلوب

prompt

النموذج الذي يُجري التحويل من صورة إلى صورة. القيمة الافتراضية `nano_banana_2`. النماذج المدعومة مطابقة لما يوفّره Codia Studio للتوليد من صورة إلى صورة. تُضبط الأرصدة في `pricing.yaml` وتُعاد عبر `GET /v2/open/limits`.

| النموذج | الأنسب لـ |
| --- | --- |
| `nano_banana_2` | تعديلات سريعة من صورة إلى صورة موجَّهة بـ prompt نصي (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. يقبل حتى 2 من `reference_images`. |
| `hy_image_3_5` | تعديلات واقعية مُوجَّهة بالمراجع بدقة 1K/2K، ولا يدعم 4K. يقبل حتى 4 من `reference_images` إلى جانب الصورة المصدر. |
| `seedream_5_pro` | تحرير صور عالي الدقة مع استدلال بصري متقدم. يدعم مُخرجات 1K و2K. |
| `seedream_5_flash` | تحرير صور سريع منخفض التكلفة. يدعم مُخرجات 1K و2K بسعر واحد. |
| `seedream_5` | تحويلات واقعية بتفاصيل دقيقة. الأحجام مبنية على 1920. |
| `seedream_4_5` | تحويلات واقعية موثوقة. الأحجام مبنية على 1920. |
| `recraft_v4` | تحويل الصور الفوتوغرافية إلى رسوم توضيحية أو أيقونات أو فن بأسلوب المتجهات. |
| `flux_3` | تحرير أصلي بدقة 1K/2K/4K مع ما يصل إلى 10 صور مُدخلة إجمالًا. |
| `flux_2_pro` | تعديلات عالية الجودة تعتمد على FLUX. |
| `flux_2_max` | فئة FLUX ذات الجودة القصوى للتعديلات المتميزة. |
| `ideogram_v4` | أحدث مسار إعادة مزج/تحرير من Ideogram للصور الغنية بالطباعة. |

model

أبعاد الإخراج الاختيارية بصيغة `WIDTHxHEIGHT`، مثل `1024x1024`. مع GPT Image 2 و2.5، يدخل الحجم في مفتاح التسعير إلى جانب `quality`. يقبل FLUX 2 Pro/Max أيضًا إعدادات الحجم المسبقة 1K/2K. تُقلَّص الطلبات التي تتجاوز الحد، بما فيها 4K، إلى نحو 4MP كحد أقصى (2048x2048 للصور المربعة)؛ ولا يُدعم إخراج 4K أصلي. تعتمد الفوترة على مساحة الإخراج بعد التعديل: ما يصل إجماليه إلى 1,048,576 بكسل يُحتسب بسعر 1K، وما يزيد على ذلك يُحتسب بسعر 2K. الحجم المحدد صراحةً له الأولوية على أي تلميح للدقة في quality.

size

مع `gpt_image` استخدم `low` أو `medium` أو `high` أو `auto`. ومع `gpt_image_2_5` (بما في ذلك Flare وSunburst) تُدعم أيضًا القيمتان `xhigh` و`max`. إذا لم تُحدَّد quality أو كانت `auto` فتُطبَّق فئة الفوترة medium. مع النماذج غير GPT، قد يحمل هذا الحقل فئة الدقة (مثل `1K` أو `2K`).

quality

لـ GPT Image فقط. يطلب خلفية شفافة أو معتمة عند دعم ذلك. تتجاهله النماذج غير GPT.

background

روابط URL إضافية لصور مرجعية لتوجيه الأسلوب أو العنصر. مع qwen_image_3_pro، يقبل image_to_image حتى 2 من reference_images.

reference_images

image

حقل ملف الصورة المصدر للتوافق (مهمل: استخدم `image` بدلًا منه).

file

رابط URL للصورة المصدر عند عدم رفع صورة

روابط URL للصور المعالَجة

code

message

روابط URL للصور المُولَّدة أو المعالَجة

image_urls

data

جسم الطلب غير صالح أو تنقصه معاملات مطلوبة

مفتاح API مفقود أو غير صالح أو تم إبطاله

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

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

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

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

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

يحوّل الصورة وفق تعليمات نصية، من إعادة تصميم الأسلوب إلى تعديل المشهد.

صورة إلى صورة

المدخلات

المخرجات

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