**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` | 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 Remix/编辑通道，适合文字排版较多的图片。 |

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 最多接受 2 张 reference_images。

reference_images

image

兼容用的源图片文件字段（已弃用：请改用 `image`）。

file

code

message

image_urls

data

请求体格式错误或缺少必填参数

Idempotency-Key 已被用于不同的请求体。

请求频率超限。请等待 `Retry-After` 响应头中指定的秒数后再重试。

根据文本指令变换图片，从风格重绘到场景编辑均可实现。

相关 API