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

Idempotency-Key

Публичный URL исходного изображения для преобразования

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 для изображений с акцентом на типографику. |

model

Необязательные размеры результата в формате `WIDTHxHEIGHT`, например `1024x1024`. Для GPT Image 2 и 2.5 размер вместе с `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 исходного изображения, если изображение не загружается

Промпт для редактирования

Необязательная модель

URL обработанных изображений

code

message

URL сгенерированных или обработанных изображений

image_urls

data

Тело запроса имеет неверный формат или в нём отсутствуют обязательные параметры

API-ключ отсутствует, недействителен или отозван

Недостаточно средств на балансе аккаунта или срок подписки истёк

У аккаунта нет доступа к этому эндпоинту

Idempotency-Key повторно использован с другим телом запроса.

Превышен лимит запросов. Перед повторной попыткой подождите столько секунд, сколько указано в заголовке `Retry-After`.

На сервере произошла непредвиденная ошибка

Преобразует изображение по текстовой инструкции — от смены стиля до изменения сцены.

Изображение в изображение

Входные данные

Выходные данные

Похожие API