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

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

code

message

image_urls

data

请求体格式错误或缺少必填参数

Idempotency-Key 已被用于不同的请求体。

请求频率超限。请等待 `Retry-After` 响应头中指定的秒数后再重试。

保留主体，根据文本提示词生成新背景。

背景替换

输入

输出

相关 API