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

Optional user-supplied key (up to 255 chars). When set, a successful (2xx) response is cached for 7 days. A retry with the same key + identical request body returns the cached response (no extra credit charged); a retry with the same key but a different body returns 409. Use to make POST safe to retry on network failures. For multipart/form-data uploads, requests are compared by form fields and file contents, so a retried upload is replayed even though the client picks a new multipart boundary.

Idempotency-Key

Public URL of the source image to transform

image_url

Text description of the desired transformation

prompt

Model that performs the image-to-image transformation. Defaults to `nano_banana_2`. Supported models match Codia Studio for image-to-image generation. Credits are configured in `pricing.yaml` and returned by `GET /v2/open/limits`.

| Model | Best for |
| --- | --- |
| `nano_banana_2` | Fast image-to-image edits guided by a text prompt (Gemini 3.1 Flash). |
| `nano_banana_pro` | Studio-quality 4K transformations with advanced reasoning (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 with Flare and Sunburst variants; supports low, medium, high, xhigh, max, and auto quality. |
| `gpt_image` | High-fidelity reference-driven edits with crisp text. Supports `quality` (`low`/`medium`/`high`/`auto`) and `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Detailed image edits with strong layout and multilingual text rendering. Supports 512/1K/2K outputs, no 4K. Accepts up to 2 `reference_images`. |
| `hy_image_3_5` | Reference-guided photorealistic edits at 1K/2K, no 4K. Accepts up to 4 `reference_images` alongside the source image. |
| `seedream_5_pro` | High-precision image editing with advanced visual reasoning. Supports 1K and 2K outputs. |
| `seedream_5_flash` | Fast, low-cost image editing. Supports 1K and 2K outputs at one price. |
| `seedream_5` | Photorealistic transformations with fine detail. Sizes are 1920-based. |
| `seedream_4_5` | Reliable photorealistic transformations. Sizes are 1920-based. |
| `recraft_v4` | Convert photos into illustrations, icons, or vector-style art. |
| `flux_3` | Native 1K/2K/4K editing with up to 10 total input images. |
| `flux_2_pro` | High-quality FLUX-driven edits. |
| `flux_2_max` | Maximum-quality FLUX tier for premium edits. |
| `ideogram_v4` | Latest Ideogram remix/edit path for typography-heavy images. |

model

Optional output dimensions as `WIDTHxHEIGHT`, e.g. `1024x1024`. For GPT Image 2 and 2.5, size contributes to the pricing key together with `quality`. FLUX 2 Pro/Max also accept 1K/2K size presets. Oversized requests, including 4K, are reduced to at most approximately 4MP (2048x2048 for square images); native 4K output is not supported. Billing uses the adjusted output area: up to 1,048,576 pixels in total uses the 1K price, and larger outputs use the 2K price. An explicit size takes precedence over a resolution hint in quality.

size

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`).

quality

GPT Image only. Requests transparent or opaque background when supported. Ignored by non-GPT models.

background

Additional reference image URLs for style or subject guidance. For qwen_image_3_pro, image_to_image accepts up to 2 reference_images.

reference_images

image

Compatible source image file field (deprecated: use `image` instead).

file

Source image URL when not uploading image

code

message

image_urls

data

The request body is malformed or missing required parameters

The API key is missing, invalid, or revoked

Account balance is insufficient or subscription has expired

Account does not have access to this endpoint

Idempotency-Key reused with a different request body.

Rate limited. Wait for the number of seconds in the `Retry-After` header before retrying.

An unexpected error occurred on the server

Transforms an image according to a text instruction, from restyling to scene edits.

Related APIs