Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-api-reference/image.change_background.md, and the index of every page is https://docs.refabric.com/llms.txt.

Image editing

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_backgroundTask: image.change_backgroundScope: tasks:runCategory: Image editing

Quick start

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())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

  • stringrequired

    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.

    pattern: ^(https://|art:|file:).+$

    Example: art:9f2c01

  • objectrequired

    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"}

  • stringoptional

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

    pattern: ^model:.+$

Output schema

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

Required-fields example

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

Full example

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

Response example

{
  "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

{
  "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.

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.

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 formatsImages, 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 countimage: one
Output formatFiles: each one line with its url and its media_type, in the job's result.
Outputs per jobOne image file per job.

Choosing a task

Errors

Related

Good to know

    Pricing: Estimate a request before you run it, or see the price of each option.

    For agents and code generation

    Schema changes follow Versioning.