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

คีย์ที่ผู้ใช้กำหนดเอง (ไม่บังคับ ยาวสูงสุด 255 อักขระ) เมื่อกำหนดไว้ การตอบกลับที่สำเร็จ (2xx) จะถูกแคชไว้ 7 วัน การลองใหม่ด้วยคีย์เดิม + เนื้อหาคำขอที่เหมือนกันทุกประการจะได้การตอบกลับที่แคชไว้ (ไม่หักเครดิตเพิ่ม) ส่วนการลองใหม่ด้วยคีย์เดิมแต่เนื้อหาคำขอต่างกันจะได้ 409 ใช้เพื่อให้ส่ง POST ซ้ำได้อย่างปลอดภัยเมื่อเครือข่ายขัดข้อง สำหรับการอัปโหลดแบบ multipart/form-data ระบบจะเปรียบเทียบคำขอจากฟิลด์ในฟอร์มและเนื้อหาไฟล์ ดังนั้นการอัปโหลดซ้ำจะได้ผลลัพธ์เดิมแม้ไคลเอนต์จะสร้าง multipart boundary ใหม่

Idempotency-Key

URL สาธารณะของรูปภาพต้นฉบับ

image_url

ข้อความอธิบายพื้นหลังใหม่ที่ต้องการ

prompt

โมเดลที่ใช้สร้างพื้นหลังใหม่ ค่าเริ่มต้นคือ `nano_banana_2` ปัจจุบันทุกโมเดลที่รองรับใช้ 13 เครดิตต่อคำขอ

| โมเดล | เหมาะสำหรับ | เครดิต |
| --- | --- | ---: |
| `nano_banana_2` | เปลี่ยนพื้นหลังได้รวดเร็ว (Gemini 3.1 Flash) เป็นค่าเริ่มต้นที่ดีสำหรับรูปภาพส่วนใหญ่ | 13 |
| `nano_banana_pro` | พื้นหลัง 4K คุณภาพระดับสตูดิโอ พร้อมแสงและเงาสะท้อนที่สมจริง | 13 |
| `ideogram_v3` | พื้นหลังแนวสไตไลซ์ แนวภาพประกอบ หรือที่มีข้อความมาก | 13 |

model

ไฟล์รูปภาพต้นฉบับ

image

ฟิลด์ไฟล์รูปภาพต้นฉบับสำหรับความเข้ากันได้ (เลิกใช้แล้ว: ให้ใช้ `image` แทน)

file

URL รูปภาพต้นฉบับ เมื่อไม่ได้อัปโหลดรูปภาพ

prompt สำหรับพื้นหลังใหม่

โมเดล (ไม่บังคับ)

URL ของรูปภาพที่ประมวลผลแล้ว

code

message

URL ของรูปภาพที่สร้างหรือประมวลผลแล้ว

image_urls

data

เนื้อหาคำขอมีรูปแบบไม่ถูกต้องหรือขาดพารามิเตอร์ที่จำเป็น

ไม่มี API key หรือ key ไม่ถูกต้องหรือถูกเพิกถอนแล้ว

ยอดคงเหลือในบัญชีไม่เพียงพอหรือการสมัครใช้งานหมดอายุแล้ว

บัญชีไม่มีสิทธิ์เข้าถึง endpoint นี้

ใช้ Idempotency-Key ซ้ำกับเนื้อหาคำขอที่ต่างออกไป

ถูกจำกัดอัตราการเรียกใช้ (rate limit) ให้รอตามจำนวนวินาทีในเฮดเดอร์ `Retry-After` ก่อนลองใหม่

เกิดข้อผิดพลาดที่ไม่คาดคิดบนเซิร์ฟเวอร์

คงวัตถุหลักไว้และสร้างพื้นหลังใหม่จาก prompt ข้อความ

เปลี่ยนพื้นหลัง

อินพุต

เอาต์พุต

API ที่เกี่ยวข้อง