**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 には対応していません。元画像に加えて最大 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 では、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

生成または処理された画像の URL

image_urls

data

リクエストボディの形式が正しくないか、必須パラメータが不足しています

API キーが指定されていないか、無効か、失効しています

アカウントの残高が不足しているか、サブスクリプションの有効期限が切れています

アカウントにこのエンドポイントへのアクセス権がありません

Idempotency-Key が異なるリクエストボディで再利用されました。

レート制限に達しました。`Retry-After` ヘッダーに示された秒数だけ待ってからリトライしてください。

サーバーで予期しないエラーが発生しました

テキストの指示に従って画像を変換します。スタイルの変更からシーンの編集まで対応します。

関連する API