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

رابط URL العام للصورة المصدر

image_url

رابط URL العام لصورة القناع (الأبيض = المنطقة المراد مسحها، الأسود = إبقاء)

mask_url

النموذج الذي يُجري الملء (inpainting). القيمة الافتراضية `codia_image_v2`. تكلفة جميع النماذج المدعومة حاليًا 5 أرصدة لكل طلب.

| النموذج | الأنسب لـ | الأرصدة |
| --- | --- | ---: |
| `codia_image_v2` | ملء نظيف وسريع للصور الفوتوغرافية وواجهات المستخدم. الأفضل عندما يكون السياق المحيط بسيطًا. | 5 |
| `nano_banana_2` | مسح ذكي مدرك للسياق يعيد بناء السياقات المعقدة (Gemini 3.1 Flash). | 5 |
| `nano_banana_pro` | مسح عالي الدقة مع إعادة بناء الخلفيات المعقدة (Gemini 3 Pro). | 5 |

model

image

حقل ملف الصورة المصدر للتوافق (مهمل: استخدم `image` بدلًا منه).

file

mask

رابط URL للصورة المصدر عند عدم رفع صورة

رابط URL لصورة القناع عند عدم رفع قناع

روابط URL للصور المعالَجة

code

message

روابط URL للصور المُولَّدة أو المعالَجة

image_urls

data

جسم الطلب غير صالح أو تنقصه معاملات مطلوبة

مفتاح API مفقود أو غير صالح أو تم إبطاله

رصيد الحساب غير كافٍ أو انتهت صلاحية الاشتراك

لا يملك الحساب صلاحية الوصول إلى نقطة النهاية هذه

أُعيد استخدام Idempotency-Key مع جسم طلب مختلف.

تم تجاوز حد المعدل. انتظر عدد الثواني المحدد في الترويسة `Retry-After` قبل إعادة المحاولة.

حدث خطأ غير متوقع في الخادم

يزيل المناطق المحددة في القناع ويملؤها بحيث يبدو كأن العنصر لم يكن موجودًا قط.

مسح العناصر

المدخلات

المخرجات

واجهات API ذات صلة