**Cost**: 13 credits per successful call.

Image Replace Background 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/replace_background' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png' \
  -F 'prompt=clean white studio background'
```

Keep the foreground subject of an image and synthesize a new background described by a text prompt. Synchronous, single-call. Combines background removal + inpainting + generative rendering in one step.

## What this API is for

Reshooting product photography against new scenes ("on a marble counter", "in front of a sunset window"), reusing portraits across campaigns, or any time you want to keep the subject and change its environment. The subject is preserved; the prompt only steers the new background.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `prompt` | yes | Natural-language description of the desired new background. Be specific about lighting, surface, and context for best results. |
| `model` | no | Model ID. Defaults to `nano_banana_2`. Also: `nano_banana_pro` (higher fidelity), `ideogram_v3` (alternative aesthetic). |

**Prompt tips**: describe the surface or scene ("clean white marble table"), the lighting ("soft studio lighting from the left"), and the mood. Avoid contradicting the subject's lighting unless you want the subject re-lit (the model may match it).

## Response

Shared `ImageUrlListSuccess` shape — `data.image_urls` is an array of CDN URLs (length 1).

## Billing & limits

- 13 credits per request from the unified Codia Open API balance.
- Synchronous, single-digit-second latency for typical inputs.

## Errors

Standard set — `400` bad input (missing `image_url` or `prompt`), `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **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_replace_background` 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

image_url

Descrição em texto do novo fundo pretendido

prompt

Modelo que sintetiza o novo fundo. A predefinição é `nano_banana_2`. Atualmente, todos os modelos suportados custam 13 créditos por pedido.

| Modelo | Ideal para | Créditos |
| --- | --- | ---: |
| `nano_banana_2` | Trocas de fundo rápidas (Gemini 3.1 Flash). Boa opção predefinida para a maioria das imagens. | 13 |
| `nano_banana_pro` | Fundos 4K com qualidade de estúdio, iluminação e reflexos realistas. | 13 |
| `ideogram_v3` | Fundos estilizados, ilustrativos ou com muito texto. | 13 |

model

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.

Mantém o motivo e gera um novo fundo a partir de um prompt de texto.

Substituir fundo

Entrada

Saída

APIs relacionadas