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

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. Untuk unggahan multipart/form-data, permintaan dibandingkan berdasarkan field formulir dan isi file, sehingga unggahan yang di-retry tetap diputar ulang meskipun klien memilih multipart boundary baru.

Idempotency-Key

URL publik gambar sumber yang akan diubah

image_url

Deskripsi teks transformasi yang diinginkan

prompt

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

| Model | Cocok untuk |
| --- | --- |
| `nano_banana_2` | Edit image-to-image yang cepat dengan panduan prompt teks (Gemini 3.1 Flash). |
| `nano_banana_pro` | Transformasi 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` | Edit berbasis referensi dengan presisi tinggi dan teks yang tajam. Mendukung `quality` (`low`/`medium`/`high`/`auto`) dan `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Edit gambar yang detail dengan layout kuat dan rendering teks multibahasa. Mendukung output 512/1K/2K, tanpa 4K. Menerima hingga 2 `reference_images`. |
| `hy_image_3_5` | Edit fotorealistis berbasis referensi pada 1K/2K, tanpa 4K. Menerima hingga 4 `reference_images` selain gambar sumber. |
| `seedream_5_pro` | Pengeditan gambar presisi tinggi dengan penalaran visual tingkat lanjut. Mendukung output 1K dan 2K. |
| `seedream_5_flash` | Pengeditan gambar cepat dan hemat biaya. Mendukung output 1K dan 2K dengan satu harga. |
| `seedream_5` | Transformasi fotorealistis dengan detail halus. Ukuran berbasis 1920. |
| `seedream_4_5` | Transformasi fotorealistis yang andal. Ukuran berbasis 1920. |
| `recraft_v4` | Mengubah foto menjadi ilustrasi, ikon, atau seni bergaya vektor. |
| `flux_3` | Pengeditan native 1K/2K/4K dengan total hingga 10 gambar input. |
| `flux_2_pro` | Edit berbasis FLUX berkualitas tinggi. |
| `flux_2_max` | Tingkat FLUX dengan kualitas maksimum untuk edit premium. |
| `ideogram_v4` | Jalur remix/edit Ideogram terbaru untuk gambar yang sarat tipografi. |

model

Dimensi output opsional dalam format `WIDTHxHEIGHT`, misalnya `1024x1024`. Untuk GPT Image 2 dan 2.5, size ikut menentukan kunci harga bersama `quality`. 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

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

Khusus GPT Image. Meminta latar belakang transparan atau opak jika didukung. Diabaikan oleh model non-GPT.

background

URL gambar referensi tambahan untuk panduan gaya atau subjek. Untuk qwen_image_3_pro, image_to_image menerima hingga 2 reference_images.

reference_images

image

Field file gambar sumber untuk kompatibilitas (usang: gunakan `image`).

file

URL gambar sumber jika tidak mengunggah gambar

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.

Mengubah gambar sesuai instruksi teks, mulai dari mengganti gaya hingga mengedit adegan.

Gambar ke Gambar

Input

Output

API terkait