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

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

image_url

Textbeschreibung des gewünschten neuen Hintergrunds

prompt

Modell, das den neuen Hintergrund erzeugt. Standard ist `nano_banana_2`. Alle unterstützten Modelle kosten derzeit 13 Credits pro Request.

| Modell | Geeignet für | Credits |
| --- | --- | ---: |
| `nano_banana_2` | Schneller Hintergrundtausch (Gemini 3.1 Flash). Guter Standard für die meisten Bilder. | 13 |
| `nano_banana_pro` | Hintergründe in Studioqualität und 4K mit realistischer Beleuchtung und Spiegelungen. | 13 |
| `ideogram_v3` | Stilisierte, illustrative oder textlastige Hintergründe. | 13 |

model

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

Behält das Motiv bei und generiert aus einem Text-Prompt einen neuen Hintergrund.

Hintergrund ersetzen

Eingabe

Ausgabe

Ähnliche APIs