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

image_url

prompt

執行圖生圖轉換的模型。預設為 `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。最多接受 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 Remix/編輯路徑，適合文字排版較多的圖片。 |

model

選填的輸出尺寸，格式為 `WIDTHxHEIGHT`，例如 `1024x1024`。對於 GPT Image 2 與 2.5，size 會與 `quality` 共同決定定價鍵。FLUX 2 Pro/Max 也接受 1K/2K 尺寸預設值。過大的請求（包括 4K）會縮減至最多約 4MP（正方形圖片為 2048x2048）；不支援原生 4K 輸出。計費依調整後的輸出面積計算：總像素不超過 1,048,576 時按 1K 價格計費，更大的輸出則按 2K 價格計費。明確指定的 size 優先於 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

code

message

image_urls

data

請求主體格式錯誤或缺少必要參數

Idempotency-Key 已被用於不同的請求主體。

已達速率限制。請等待 `Retry-After` 標頭中指定的秒數後再重試。

依文字指示轉換圖片，從風格重繪到場景編輯皆可。

以圖生圖

輸入

輸出

相關 API