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

Clé facultative fournie par l’utilisateur (jusqu’à 255 caractères). Si elle est définie, une réponse réussie (2xx) est mise en cache pendant 7 jours. Une nouvelle tentative avec la même clé et un corps de requête identique renvoie la réponse en cache (sans crédit supplémentaire facturé) ; une nouvelle tentative avec la même clé mais un corps différent renvoie 409. Permet de relancer un POST sans risque en cas d’erreur réseau. Pour les envois multipart/form-data, les requêtes sont comparées sur la base des champs du formulaire et du contenu des fichiers : un envoi relancé est donc bien rejoué même si le client choisit une nouvelle frontière multipart.

Idempotency-Key

URL publique de l’image source à transformer

image_url

Description textuelle de la transformation souhaitée

prompt

Modèle qui effectue la transformation image-image. Par défaut : `nano_banana_2`. Les modèles pris en charge sont les mêmes que dans Codia Studio pour la génération image-image. Les crédits sont configurés dans `pricing.yaml` et renvoyés par `GET /v2/open/limits`.

| Modèle | Idéal pour |
| --- | --- |
| `nano_banana_2` | Retouches image-image rapides guidées par un prompt textuel (Gemini 3.1 Flash). |
| `nano_banana_pro` | Transformations 4K de qualité studio avec raisonnement avancé (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 avec les variantes Flare et Sunburst ; prend en charge les qualités low, medium, high, xhigh, max et auto. |
| `gpt_image` | Retouches haute fidélité guidées par référence, avec un texte net. Prend en charge `quality` (`low`/`medium`/`high`/`auto`) et `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Retouches détaillées avec une bonne maîtrise de la mise en page et du rendu de texte multilingue. Sorties 512/1K/2K, pas de 4K. Accepte jusqu’à 2 `reference_images`. |
| `hy_image_3_5` | Retouches photoréalistes guidées par référence en 1K/2K, pas de 4K. Accepte jusqu’à 4 `reference_images` en plus de l’image source. |
| `seedream_5_pro` | Retouche d’image de haute précision avec raisonnement visuel avancé. Prend en charge les sorties 1K et 2K. |
| `seedream_5_flash` | Retouche d’image rapide et économique. Prend en charge les sorties 1K et 2K au même prix. |
| `seedream_5` | Transformations photoréalistes aux détails fins. Tailles basées sur 1920. |
| `seedream_4_5` | Transformations photoréalistes fiables. Tailles basées sur 1920. |
| `recraft_v4` | Convertit des photos en illustrations, icônes ou visuels de style vectoriel. |
| `flux_3` | Retouche native 1K/2K/4K avec jusqu’à 10 images d’entrée au total. |
| `flux_2_pro` | Retouches FLUX de haute qualité. |
| `flux_2_max` | Niveau FLUX de qualité maximale pour des retouches premium. |
| `ideogram_v4` | Dernière version du mode remix/retouche d’Ideogram, pour les images à forte composante typographique. |

model

Dimensions de sortie facultatives au format `WIDTHxHEIGHT`, par ex. `1024x1024`. Pour GPT Image 2 et 2.5, la taille entre dans la clé de tarification avec `quality`. FLUX 2 Pro/Max acceptent aussi les préréglages de taille 1K/2K. Les requêtes surdimensionnées, 4K compris, sont réduites à environ 4MP au maximum (2048x2048 pour une image carrée) ; la sortie 4K native n’est pas prise en charge. La facturation se base sur la surface de sortie ajustée : jusqu’à 1,048,576 pixels au total, le prix 1K s’applique ; au-delà, c’est le prix 2K. Une valeur size explicite prime sur une indication de résolution dans quality.

size

Pour `gpt_image`, utilisez `low`, `medium`, `high` ou `auto`. Pour `gpt_image_2_5` (y compris Flare et Sunburst), `xhigh` et `max` sont également pris en charge. Si quality est omis ou vaut `auto`, le palier de facturation medium s’applique. Pour les modèles non GPT, ce champ peut contenir le palier de résolution (par exemple `1K` ou `2K`).

quality

GPT Image uniquement. Demande un arrière-plan transparent ou opaque lorsque c’est pris en charge. Ignoré par les modèles non GPT.

background

URL d’images de référence supplémentaires pour guider le style ou le sujet. Pour qwen_image_3_pro, image_to_image accepte jusqu’à 2 reference_images.

reference_images

image

Champ de fichier image source conservé pour compatibilité (obsolète : utilisez plutôt `image`).

file

URL de l’image source si aucune image n’est téléversée

code

message

image_urls

data

Le corps de la requête est mal formé ou des paramètres obligatoires sont manquants

La clé d’API est manquante, invalide ou révoquée

Le solde du compte est insuffisant ou l’abonnement a expiré

Le compte n’a pas accès à cet endpoint

Idempotency-Key réutilisée avec un corps de requête différent.

Limite de débit atteinte. Attendez le nombre de secondes indiqué dans l’en-tête `Retry-After` avant de réessayer.

Une erreur inattendue s’est produite sur le serveur

Transforme une image selon une instruction textuelle, du changement de style à la modification de la scène.

Image vers image

Entrée

Sortie

APIs associées