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

Chave opcional fornecida pelo utilizador (até 255 caracteres). Quando definida, uma resposta bem-sucedida (2xx) fica em cache durante 7 dias. Uma nova tentativa com a mesma chave e o mesmo corpo de pedido devolve a resposta em cache (sem cobrança adicional de créditos); uma nova tentativa com a mesma chave, mas com um corpo diferente, devolve 409. Utilize-a para que repetir um POST após falhas de rede seja seguro. Nos carregamentos multipart/form-data, os pedidos são comparados pelos campos do formulário e pelo conteúdo dos ficheiros, pelo que um carregamento repetido é reproduzido mesmo que o cliente escolha um novo boundary multipart.

Idempotency-Key

URL público da imagem de origem a transformar

image_url

Descrição em texto da transformação pretendida

prompt

Modelo que faz a transformação de imagem para imagem. A predefinição é `nano_banana_2`. Os modelos suportados são os mesmos do Codia Studio para geração de imagem para imagem. Os créditos são configurados em `pricing.yaml` e devolvidos por `GET /v2/open/limits`.

| Modelo | Ideal para |
| --- | --- |
| `nano_banana_2` | Edições rápidas de imagem para imagem orientadas por um prompt de texto (Gemini 3.1 Flash). |
| `nano_banana_pro` | Transformações 4K com qualidade de estúdio e raciocínio avançado (Gemini 3 Pro). |
| `gpt_image_2_5` | GPT Image 2.5 com as variantes Flare e Sunburst; suporta as qualidades low, medium, high, xhigh, max e auto. |
| `gpt_image` | Edições de alta fidelidade orientadas por referências, com texto nítido. Suporta `quality` (`low`/`medium`/`high`/`auto`) e `background` (`transparent`/`opaque`/`auto`). |
| `qwen_image_3_pro` | Edições detalhadas com bom controlo de layout e renderização de texto multilingue. Suporta saídas 512/1K/2K, sem 4K. Aceita até 2 `reference_images`. |
| `hy_image_3_5` | Edições fotorrealistas orientadas por referências em 1K/2K, sem 4K. Aceita até 4 `reference_images` além da imagem de origem. |
| `seedream_5_pro` | Edição de alta precisão com raciocínio visual avançado. Suporta saídas 1K e 2K. |
| `seedream_5_flash` | Edição rápida e de baixo custo. Suporta saídas 1K e 2K ao mesmo preço. |
| `seedream_5` | Transformações fotorrealistas com detalhe fino. Os tamanhos têm base 1920. |
| `seedream_4_5` | Transformações fotorrealistas fiáveis. Os tamanhos têm base 1920. |
| `recraft_v4` | Converte fotografias em ilustrações, ícones ou arte em estilo vetorial. |
| `flux_3` | Edição nativa em 1K/2K/4K com até 10 imagens de entrada no total. |
| `flux_2_pro` | Edições de alta qualidade com FLUX. |
| `flux_2_max` | Nível FLUX de qualidade máxima para edições premium. |
| `ideogram_v4` | O fluxo mais recente de remix/edição da Ideogram para imagens com muita tipografia. |

model

Dimensões de saída opcionais no formato `WIDTHxHEIGHT`, por exemplo `1024x1024`. Para GPT Image 2 e 2.5, o tamanho entra na chave de preço juntamente com `quality`. FLUX 2 Pro/Max também aceitam as predefinições de tamanho 1K/2K. Os pedidos demasiado grandes, incluindo 4K, são reduzidos para um máximo de aproximadamente 4MP (2048x2048 para imagens quadradas); a saída 4K nativa não é suportada. A faturação usa a área de saída ajustada: até 1,048,576 píxeis no total aplica-se o preço de 1K, e as saídas maiores usam o preço de 2K. Um size explícito tem prioridade sobre uma indicação de resolução em quality.

size

Para `gpt_image`, utilize `low`, `medium`, `high` ou `auto`. Para `gpt_image_2_5` (incluindo Flare e Sunburst), também são suportados `xhigh` e `max`. Se quality for omitido ou `auto`, é usado o escalão de faturação medium. Para modelos não GPT, este campo pode indicar o escalão de resolução (por exemplo, `1K` ou `2K`).

quality

Apenas GPT Image. Pede um fundo transparente ou opaco quando suportado. Ignorado pelos modelos não GPT.

background

URL de imagens de referência adicionais para orientar o estilo ou o motivo. Para qwen_image_3_pro, image_to_image aceita até 2 reference_images.

reference_images

image

Campo compatível para o ficheiro da imagem de origem (obsoleto: utilize `image`).

file

URL da imagem de origem quando a imagem não é carregada

code

message

image_urls

data

O corpo do pedido está malformado ou faltam parâmetros obrigatórios

A chave de API está em falta, é inválida ou foi revogada

O saldo da conta é insuficiente ou a subscrição expirou

Idempotency-Key reutilizada com um corpo de pedido diferente.

Limite de pedidos atingido. Aguarde o número de segundos indicado no cabeçalho `Retry-After` antes de tentar novamente.

Transforma uma imagem de acordo com uma instrução em texto, desde mudanças de estilo a edições de cena.

Imagem para imagem

Entrada

Saída

APIs relacionadas