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

Image Object Erase 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/object_erase' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./photo.png' \
  -F 'mask=@./mask.png'
```

Remove specific regions of an image as identified by a **mask** image, and inpaint the gap so the result looks like the object was never there. Synchronous.

## What this API is for

Deleting people from background plates, removing unwanted objects from product shots, cleaning up screenshots before redistribution. Unlike `watermark_remove` (which auto-detects), this endpoint requires you to **specify exactly what to erase** via a binary mask.

## Mask format

`mask_url` must point to an image with the **same dimensions** as `image_url`:

- **White (255)** pixels = area to erase + inpaint.
- **Black (0)** pixels = keep as-is.
- Grayscale values in between produce partial blending; for crisp removal, threshold your mask to pure black/white.

The mask can be a separate PNG you generated client-side (e.g. from a brush UI or a segmentation model) or an alpha-channel cutout. Soft edges in the mask produce softer transitions in the result.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `mask_url` | yes | Public URL of the mask image (same dimensions as source). |
| `model` | no | Model ID. Defaults to `codia_image_v2`. Also: `nano_banana_2`, `nano_banana_pro` (higher fidelity at higher latency). |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one CDN URL of the cleaned image.

## Billing & limits

- 5 credits per request from the unified Codia Open API balance.
- Synchronous.

## Errors

Standard set; in particular `400` on size mismatch between image and mask.

> **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_object_erase` instead. Inputs and credit cost are identical.

選填，由使用者自訂的冪等鍵（最多 255 個字元）。設定後，成功（2xx）的回應會快取 7 天。以相同的鍵 + 相同的請求主體重試時，會回傳快取的回應（不另外扣除點數）；以相同的鍵但不同的請求主體重試，則回傳 409。可讓 POST 請求在網路故障時安全重試。對於 multipart/form-data 上傳，請求會依表單欄位與檔案內容比對，因此即使用戶端產生新的 multipart boundary，重試的上傳仍會重播先前的結果。

Idempotency-Key

image_url

遮罩圖片的公開 URL（白色 = 要擦除的區域，黑色 = 保留）

mask_url

執行修補填色（inpainting）的模型。預設為 `codia_image_v2`。目前所有支援的模型每次請求皆扣除 5 點。

| 模型 | 適用情境 | 點數 |
| --- | --- | ---: |
| `codia_image_v2` | 乾淨、快速的修補，適用於照片與 UI。周圍內容單純時效果最佳。 | 5 |
| `nano_banana_2` | 具 AI 理解能力的擦除，可重建複雜的周邊內容（Gemini 3.1 Flash）。 | 5 |
| `nano_banana_pro` | 高保真擦除，可重建精細複雜的背景（Gemini 3 Pro）。 | 5 |

model

image

相容用的來源圖片檔案欄位（已棄用：請改用 `image`）。

file

mask

未上傳圖片時使用的來源圖片 URL

未上傳遮罩時使用的遮罩圖片 URL

code

message

image_urls

data

請求主體格式錯誤或缺少必要參數

Idempotency-Key 已被用於不同的請求主體。

已達速率限制。請等待 `Retry-After` 標頭中指定的秒數後再重試。

移除遮罩標記的區域並自動填補，讓物件看起來彷彿從未存在。

物件消除

輸入

輸出

相關 API