**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` | Flare 및 Sunburst 변형을 제공하는 GPT Image 2.5. 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는 지원하지 않습니다. `reference_images`는 최대 2개까지 허용됩니다. |
| `hy_image_3_5` | 1K/2K에서의 참조 기반 사실적 편집으로, 4K는 지원하지 않습니다. 원본 이미지와 함께 `reference_images`를 최대 4개까지 허용합니다. |
| `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에서는 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는 reference_images를 최대 2개까지 허용합니다.

reference_images

image

호환용 원본 이미지 파일 필드(지원 중단: 대신 `image`를 사용하십시오).

file

이미지를 업로드하지 않을 때 사용하는 원본 이미지 URL

code

message

image_urls

data

요청 본문의 형식이 잘못되었거나 필수 매개변수가 누락되었습니다

API 키가 없거나, 유효하지 않거나, 폐기되었습니다

계정 잔액이 부족하거나 구독이 만료되었습니다

계정에 이 엔드포인트에 대한 액세스 권한이 없습니다

Idempotency-Key가 다른 요청 본문과 함께 재사용되었습니다.

속도 제한에 도달했습니다. `Retry-After` 헤더에 표시된 초만큼 기다린 후 재시도하십시오.

서버에서 예기치 않은 오류가 발생했습니다

텍스트 지시에 따라 이미지를 변환합니다. 스타일 변경부터 장면 편집까지 지원합니다.

이미지 투 이미지

입력

출력

관련 API