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

Kunci opsional dari pengguna (maksimal 255 karakter). Jika diisi, respons sukses (2xx) di-cache selama 7 hari. Retry dengan kunci yang sama + body permintaan yang identik mengembalikan respons dari cache (tanpa potongan kredit tambahan); retry dengan kunci yang sama tetapi body berbeda mengembalikan 409. Gunakan agar POST aman di-retry saat terjadi gangguan jaringan. Untuk unggahan multipart/form-data, permintaan dibandingkan berdasarkan field formulir dan isi file, sehingga unggahan yang di-retry tetap diputar ulang meskipun klien memilih multipart boundary baru.

Idempotency-Key

image_url

Deskripsi teks latar belakang baru yang diinginkan

prompt

Model yang membuat latar belakang baru. Default-nya `nano_banana_2`. Saat ini semua model yang didukung memakan 13 kredit per permintaan.

| Model | Cocok untuk | Kredit |
| --- | --- | ---: |
| `nano_banana_2` | Penggantian latar belakang yang cepat (Gemini 3.1 Flash). Default yang baik untuk sebagian besar gambar. | 13 |
| `nano_banana_pro` | Latar belakang 4K berkualitas studio dengan pencahayaan dan pantulan yang realistis. | 13 |
| `ideogram_v3` | Latar belakang bergaya, ilustratif, atau sarat teks. | 13 |

model

image

Field file gambar sumber untuk kompatibilitas (usang: gunakan `image`).

file

URL gambar sumber jika tidak mengunggah gambar

code

message

image_urls

data

Body permintaan tidak valid atau parameter wajib tidak ada

API key tidak ada, tidak valid, atau sudah dicabut

Saldo akun tidak mencukupi atau langganan telah berakhir

Akun tidak memiliki akses ke endpoint ini

Idempotency-Key dipakai ulang dengan body permintaan yang berbeda.

Terkena rate limit. Tunggu selama jumlah detik di header `Retry-After` sebelum mencoba lagi.

Mempertahankan subjek dan membuat latar belakang baru dari prompt teks.

Ganti Latar Belakang

Input

Output

API terkait