# Change an image's background

> Put a finished image on a new background — a backdrop from your library, a photo, a scene you describe, or none at all (a transparent PNG) — keeping everything in front of it as it is. Delivered as one image file.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/image.change_background` · **Task:** `image.change_background` · **Scope:** `tasks:run` · **Category:** Image editing

Send a finished image and choose its new backdrop: one from your library, a photo, a scene in words, or none at all. The person, the garment and the styling in front of it are kept.

## Quick start

```python
import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/image.change_background",
    headers=headers,
    json={
        "image": "art:9f2c01",
        "background": {
            "type": "library",
            "background": "background:4417",
        },
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())
```

```javascript
const headers = {
  Authorization: `Key ${process.env.REFABRIC_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch("https://api.refabric.com/v1/tasks/image.change_background", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image": "art:9f2c01",
    "background": {
      "type": "library",
      "background": "background:4417"
    }
  }),
}).then((r) => r.json());
console.log(job.job_id);

let status = job;
while (status.lifecycle !== "terminal") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await fetch(job.status_url, { headers }).then((r) => r.json());
}

console.log(await fetch(job.result_url, { headers }).then((r) => r.json()));
```

```bash
curl -X POST "https://api.refabric.com/v1/tasks/image.change_background" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"image":"art:9f2c01","background":{"type":"library","background":"background:4417"}}'
```

## Input schema

- `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — The finished image whose background to replace; the person, the garment and the styling are kept. As one string: a URL, a file from an earlier result (`art:…` or its url) or an upload (`file:…`). If it is one of your files placed in a project or on a design in the Refabric app, the result is filed there too.
  Example: `art:9f2c01`
- `background` (object, _required_) — The new backdrop, chosen by `type`: `library` (a `background:<id>`), `image` (a photo of the backdrop), `prompt` (the scene in words) or `transparent` (no backdrop).
  Example: `{"type":"library","background":"background:4417"}`
  - type: library — A backdrop from your library (`GET /v1/refs/background`).
    - `type` (string, _required_) — Picks this alternative: `library`.
      Values: `library`
    - `background` (string, _required_, pattern: ^background:.+$) — A `background:<id>` handle, listed at `GET /v1/refs/background`.
  - type: image — A photo of the backdrop to use.
    - `type` (string, _required_) — Picks this alternative: `image`.
      Values: `image`
    - `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — A picture, as one string: a URL, a file from an earlier result (`art:…`, or its `url`) or an upload (`file:…`).
  - type: prompt — The scene in words; it is the whole instruction.
    - `type` (string, _required_) — Picks this alternative: `prompt`.
      Values: `prompt`
    - `prompt` (string, _required_, min length 1) — What you want, in words.
  - type: transparent — No backdrop: the result is a PNG with a transparent background.
    - `type` (string, _required_) — Picks this alternative: `transparent`.
      Values: `transparent`
- `model` (string, _optional_, pattern: ^model:.+$) — The model the image shows, as a `model:<id>` handle (`GET /v1/refs/model`). An image from a shoot, or an edit of one, already carries its model; send `model` for any other picture (an upload, a url).

## Required-fields example

```json
{
  "image": "art:9f2c01",
  "background": {
    "type": "library",
    "background": "background:4417"
  }
}
```

## Full example

```json
{
  "image": "art:9f2c01",
  "background": {
    "type": "library",
    "background": "background:4417"
  }
}
```

## Output schema

- `files` (array<object>, _optional_) — One file: the image on its new background (`image/png` with a transparent background when you chose `transparent`). Pass it on to another edit to continue from it.

## Response example

```json
{
  "job_id": "d2b3c4d500004000800000000000000b",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000b",
  "result_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000b/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d500004000800000000000000b/cancel"
}
```

## Result example

```json
{
  "job_id": "d2b3c4d500004000800000000000000b",
  "files": [
    {
      "file": "art:9f2c03",
      "url": "https://files.example.com/image.change_background/1.png",
      "media_type": "image/png",
      "task": "image.change_background",
      "job_id": "d2b3c4d500004000800000000000000b",
      "created_at": "2026-10-01T09:12:40Z"
    }
  ],
  "has_more": false
}
```

`background` is a choice by `type`: `library` (a `background:<id>` from GET /v1/refs/background), `image` ({type: image, image}), `prompt` ({type: prompt, prompt: "a sunlit marble hall"}) or `transparent` ({type: transparent}, a PNG with a transparent background). The image is one of your products, so the result is saved on that product too.

## Built for

- A shoot image placed in a new setting
- A transparent cut-out for a web shop or a layout
- The same look shown in several scenes

## What you get

- One image on its new background — a PNG with a transparent background when you choose `transparent`.

## Specs

- **Input formats:** Images, each one string: a URL, an upload (`file:…`) or a file from an earlier result (`art:…`). Upload types and sizes: `GET /v1/meta` `limits.upload`.
- **Input count:** `image`: one
- **Output format:** Files: each one line with its `url` and its `media_type`, in the job's result.
- **Outputs per job:** One image file per job.

## Choosing a task

- Use this when the whole backdrop behind the subject should change. Use `image.glam` when one detail you name should change and the rest stay as it is.

## Errors

- `field_not_accepted`
- `invalid_request`
- `not_found`
- `permission_denied`
- `insufficient_credits`
- `content_refused`
- `processing_failed`
- `invalid_option`
- `field_not_supported`

## Related

- `background.create` — It runs before: its result is this input.
- `photoshoot.create` — It runs before: its result is this input.
- `image.upscale` — It runs after: it takes this task's result.

## For agents and code generation

- https://api.refabric.com/v1/tasks/image.change_background/llms.txt
- https://api.refabric.com/v1/tasks/image.change_background/openapi.json
- GET https://api.refabric.com/v1/tasks/image.change_background