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

Optionaler, vom Client festgelegter Schlüssel (bis zu 255 Zeichen). Ist er gesetzt, wird eine erfolgreiche (2xx) Antwort 7 Tage lang zwischengespeichert. Eine Wiederholung mit demselben Schlüssel und identischem Request-Body liefert die gespeicherte Antwort (ohne zusätzliche Credits); eine Wiederholung mit demselben Schlüssel, aber anderem Body liefert 409. Damit lassen sich POST-Requests bei Netzwerkfehlern gefahrlos wiederholen. Bei multipart/form-data-Uploads werden Requests anhand der Formularfelder und Dateiinhalte verglichen, sodass ein wiederholter Upload auch dann als Wiederholung erkannt wird, wenn der Client eine neue Multipart-Boundary wählt.

Idempotency-Key

Öffentliche URL des zu transformierenden Quellbildes

image_url

Textbeschreibung der gewünschten Transformation

prompt

Modell, das die Bild-zu-Bild-Transformation ausführt. Standard ist `nano_banana_2`. Die unterstützten Modelle entsprechen denen von Codia Studio für die Bild-zu-Bild-Generierung. Die Credits sind in `pricing.yaml` konfiguriert und werden von `GET /v2/open/limits` zurückgegeben.

| Modell | Geeignet für |
| --- | --- |
| `nano_banana_2` | Schnelle Bild-zu-Bild-Bearbeitung, gesteuert durch einen Text-Prompt (Gemini 3.1 Flash). |
| `nano_banana_pro` | Transformationen in Studioqualität und 4K mit fortgeschrittenem Reasoning (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 mit den Varianten Flare und Sunburst; unterstützt die Qualitätsstufen low, medium, high, xhigh, max und auto. |
| `gpt_image` | Hochpräzise, referenzbasierte Bearbeitung mit gestochen scharfem Text. Unterstützt `quality` (`low`/`medium`/`high`/`auto`) und `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Detaillierte Bildbearbeitung mit starkem Layout und mehrsprachigem Text-Rendering. Unterstützt Ausgaben in 512/1K/2K, kein 4K. Akzeptiert bis zu 2 `reference_images`. |
| `hy_image_3_5` | Referenzgesteuerte fotorealistische Bearbeitung in 1K/2K, kein 4K. Akzeptiert zusätzlich zum Quellbild bis zu 4 `reference_images`. |
| `seedream_5_pro` | Hochpräzise Bildbearbeitung mit fortgeschrittenem visuellem Reasoning. Unterstützt Ausgaben in 1K und 2K. |
| `seedream_5_flash` | Schnelle, günstige Bildbearbeitung. Unterstützt Ausgaben in 1K und 2K zum selben Preis. |
| `seedream_5` | Fotorealistische Transformationen mit feinen Details. Größen basieren auf 1920. |
| `seedream_4_5` | Zuverlässige fotorealistische Transformationen. Größen basieren auf 1920. |
| `recraft_v4` | Wandelt Fotos in Illustrationen, Icons oder Grafiken im Vektorstil um. |
| `flux_3` | Native Bearbeitung in 1K/2K/4K mit insgesamt bis zu 10 Eingabebildern. |
| `flux_2_pro` | Hochwertige Bearbeitung mit FLUX. |
| `flux_2_max` | FLUX-Stufe mit maximaler Qualität für Premium-Bearbeitungen. |
| `ideogram_v4` | Neuester Remix-/Bearbeitungsmodus von Ideogram für typografielastige Bilder. |

model

Optionale Ausgabemaße als `WIDTHxHEIGHT`, z. B. `1024x1024`. Bei GPT Image 2 und 2.5 fließt die Größe zusammen mit `quality` in den Preisschlüssel ein. FLUX 2 Pro/Max akzeptieren außerdem die Größenvorgaben 1K/2K. Zu große Anfragen, einschließlich 4K, werden auf höchstens etwa 4MP reduziert (2048x2048 bei quadratischen Bildern); native 4K-Ausgabe wird nicht unterstützt. Abgerechnet wird nach der angepassten Ausgabefläche: bis insgesamt 1,048,576 Pixel gilt der 1K-Preis, für größere Ausgaben der 2K-Preis. Eine explizite size hat Vorrang vor einem Auflösungshinweis in quality.

size

Für `gpt_image` verwenden Sie `low`, `medium`, `high` oder `auto`. Für `gpt_image_2_5` (einschließlich Flare und Sunburst) werden zusätzlich `xhigh` und `max` unterstützt. Ohne Angabe von quality oder mit `auto` gilt die Abrechnungsstufe medium. Bei Nicht-GPT-Modellen kann dieses Feld die Auflösungsstufe enthalten (zum Beispiel `1K` oder `2K`).

quality

Nur GPT Image. Fordert einen transparenten oder deckenden Hintergrund an, sofern unterstützt. Wird von Nicht-GPT-Modellen ignoriert.

background

Zusätzliche Referenzbild-URLs zur Steuerung von Stil oder Motiv. Bei qwen_image_3_pro akzeptiert image_to_image bis zu 2 reference_images.

reference_images

image

Kompatibilitätsfeld für die Quellbilddatei (veraltet: verwenden Sie stattdessen `image`).

file

URL des Quellbildes, wenn kein Bild hochgeladen wird

code

message

URLs der generierten oder verarbeiteten Bilder

image_urls

data

Der Request-Body ist fehlerhaft oder es fehlen erforderliche Parameter

Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen

Das Kontoguthaben reicht nicht aus oder das Abonnement ist abgelaufen

Das Konto hat keinen Zugriff auf diesen Endpunkt

Idempotency-Key mit einem anderen Request-Body wiederverwendet.

Rate-Limit erreicht. Warten Sie vor einem erneuten Versuch die im Header `Retry-After` angegebene Anzahl an Sekunden.

Auf dem Server ist ein unerwarteter Fehler aufgetreten

Verändert ein Bild anhand einer Textanweisung, vom neuen Stil bis zu Änderungen an der Szene.

Bild zu Bild

Eingabe

Ausgabe

Ähnliche APIs