Records & libraries

Add a background

Turn a photo of a place, or of a studio backdrop, into a background in your library: background:<id>.

Endpoint: POST https://api.refabric.com/v1/tasks/background.createTask: background.createScope: tasks:runCategory: Records & libraries

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/background.create",
    headers=headers,
    json={
        "image": "https://cdn.example.com/sets/loft-window.jpg",
    },
).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 backdrop photo, as one string: a public https:// URL, a file from an earlier result (art:… or its url) or an upload (file:…).
pattern: ^(https://|art:|file:).+$
Example: https://cdn.example.com/sets/loft-window.jpg
stringoptionalDefault: scene
What the backdrop photo shows. It decides how a shoot uses it. Most backdrop photos show a place, and scene sets the model in that place; only a plain one-colour backdrop needs studio.
Values
- scene — A photo of a place or setting. A shoot sets the model in this place.
- studio — A plain studio backdrop of one colour. A shoot puts the model on that exact colour, as a clean studio photo. When the photo is a plain one-colour backdrop (white, grey, beige) and you want studio shots on that colour.
Example: scene

Output schema

array<object>optional
ONE file: the backdrop, background:<id> — its url is the backdrop image. Pass the handle to image.change_background or a shoot's background; GET /v1/refs/background lists it.

Required-fields example

{
  "image": "https://cdn.example.com/sets/loft-window.jpg"
}

Full example

{
  "image": "https://cdn.example.com/sets/loft-window.jpg",
  "kind": "scene"
}

Response example

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

Result example

{
  "job_id": "3a9d8c7b6e5f4a3b9c2d1e0f9a8b7c6d",
  "files": [
    {
      "file": "background:48213",
      "url": "https://files.example.com/background.create/1.png",
      "media_type": "image/png",
      "task": "background.create",
      "job_id": null,
      "created_at": null
    }
  ],
  "has_more": false
}

kind: studio files a studio backdrop; scene (the default) a place. job_id and created_at are null for a background.

Send a photo of a place, or of a plain studio backdrop, and get a background in your library, so a shoot can set your models there.

Built for

Your own locations for photoshoots
A studio backdrop in your brand's colour
Swapping a product photo's background for your own

What you get

One background: file in your library; pass the handle to image.change_background or to a shoot's background.

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	One `background:` file, an image: its `url` is the picture and its `media_type` the image's type; it carries no `data`.
Outputs per job	One library file: the background.

Errors

image.change_background · It runs after: it takes this task's result.
photoshoot.create · It runs after: it takes this task's result.
pose.create · It does a neighbouring job.

Good to know

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

For agents and code generation

https://api.refabric.com/v1/tasks/background.create/llms.txt
https://api.refabric.com/v1/tasks/background.create/openapi.json
GET https://api.refabric.com/v1/tasks/background.create

Schema changes follow Versioning.