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

Clave opcional proporcionada por el usuario (hasta 255 caracteres). Si se indica, una respuesta correcta (2xx) se guarda en caché durante 7 días. Un reintento con la misma clave y un cuerpo de solicitud idéntico devuelve la respuesta en caché (sin cobrar créditos adicionales); un reintento con la misma clave pero un cuerpo distinto devuelve 409. Úsala para que reintentar un POST tras un fallo de red sea seguro. En las subidas multipart/form-data, las solicitudes se comparan por los campos del formulario y el contenido de los archivos, de modo que una subida reintentada se reproduce aunque el cliente elija un nuevo boundary multipart.

Idempotency-Key

URL pública de la imagen de origen que se va a transformar

image_url

Descripción en texto de la transformación que quieres

prompt

Modelo que realiza la transformación de imagen a imagen. El valor predeterminado es `nano_banana_2`. Los modelos admitidos coinciden con los de Codia Studio para la generación de imagen a imagen. Los créditos se configuran en `pricing.yaml` y los devuelve `GET /v2/open/limits`.

| Modelo | Ideal para |
| --- | --- |
| `nano_banana_2` | Ediciones rápidas de imagen a imagen guiadas por un prompt de texto (Gemini 3.1 Flash). |
| `nano_banana_pro` | Transformaciones 4K con calidad de estudio y razonamiento avanzado (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 con las variantes Flare y Sunburst; admite las calidades low, medium, high, xhigh, max y auto. |
| `gpt_image` | Ediciones de alta fidelidad guiadas por referencias, con texto nítido. Admite `quality` (`low`/`medium`/`high`/`auto`) y `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Ediciones detalladas con un sólido control del layout y renderizado de texto multilingüe. Admite salidas 512/1K/2K, sin 4K. Acepta hasta 2 `reference_images`. |
| `hy_image_3_5` | Ediciones fotorrealistas guiadas por referencias en 1K/2K, sin 4K. Acepta hasta 4 `reference_images` además de la imagen de origen. |
| `seedream_5_pro` | Edición de alta precisión con razonamiento visual avanzado. Admite salidas 1K y 2K. |
| `seedream_5_flash` | Edición rápida y económica. Admite salidas 1K y 2K al mismo precio. |
| `seedream_5` | Transformaciones fotorrealistas con gran nivel de detalle. Los tamaños se basan en 1920. |
| `seedream_4_5` | Transformaciones fotorrealistas fiables. Los tamaños se basan en 1920. |
| `recraft_v4` | Convierte fotos en ilustraciones, iconos o arte de estilo vectorial. |
| `flux_3` | Edición nativa en 1K/2K/4K con hasta 10 imágenes de entrada en total. |
| `flux_2_pro` | Ediciones de alta calidad con FLUX. |
| `flux_2_max` | Nivel FLUX de máxima calidad para ediciones premium. |
| `ideogram_v4` | La vía de remix/edición más reciente de Ideogram para imágenes con mucha tipografía. |

model

Dimensiones de salida opcionales en formato `WIDTHxHEIGHT`, p. ej., `1024x1024`. En GPT Image 2 y 2.5, el tamaño forma parte de la clave de precio junto con `quality`. FLUX 2 Pro/Max también aceptan los preajustes de tamaño 1K/2K. Las solicitudes demasiado grandes, incluidas las de 4K, se reducen a un máximo aproximado de 4MP (2048x2048 para imágenes cuadradas); no se admite la salida 4K nativa. La facturación usa el área de salida ajustada: hasta 1,048,576 píxeles en total se aplica el precio de 1K, y las salidas más grandes usan el precio de 2K. Un size explícito tiene prioridad sobre una indicación de resolución en quality.

size

Para `gpt_image`, usa `low`, `medium`, `high` o `auto`. Para `gpt_image_2_5` (incluidos Flare y Sunburst), también se admiten `xhigh` y `max`. Si se omite quality o se usa `auto`, se aplica el tramo de facturación medium. En los modelos que no son GPT, este campo puede indicar el nivel de resolución (por ejemplo, `1K` o `2K`).

quality

Solo GPT Image. Solicita un fondo transparente u opaco cuando se admite. Los modelos que no son GPT lo ignoran.

background

URL de imágenes de referencia adicionales para orientar el estilo o el sujeto. Con qwen_image_3_pro, image_to_image acepta hasta 2 reference_images.

reference_images

image

Campo compatible para el archivo de imagen de origen (obsoleto: usa `image` en su lugar).

file

URL de la imagen de origen si no se sube la imagen

code

message

URL de las imágenes generadas o procesadas

image_urls

data

El cuerpo de la solicitud tiene un formato incorrecto o le faltan parámetros obligatorios

Falta la clave de API, no es válida o se ha revocado

El saldo de la cuenta es insuficiente o la suscripción ha caducado

La cuenta no tiene acceso a este endpoint

Idempotency-Key reutilizada con un cuerpo de solicitud distinto.

Límite de frecuencia alcanzado. Espera el número de segundos indicado en el encabezado `Retry-After` antes de reintentar.

Se ha producido un error inesperado en el servidor

Transforma una imagen según una instrucción de texto, desde cambios de estilo hasta ediciones de la escena.

Imagen a imagen

Entrada

Salida

APIs relacionadas