import requests

response = requests.post(
    f"https://api.stability.ai/v2beta/stable-image/edit/replace-background-and-relight",
    headers={
        "authorization": f"Bearer sk-MYAPIKEY",
        "accept": "image/*"
    },
    files={
        "subject_image": open("./husky-in-a-field.png", "rb")
    },
    data={
        "background_prompt": "cinematic lighting",
        "output_format": "webp",
    },
)

print("Generation ID:", response.json().get('id'))

{
  "id": "a6dc6c6e20acda010fe14d71f180658f2896ed9b4ec25aa99a6ff06c796987c4"
}

Edit

Replace Background and Relight (async)

The Replace Background and Relight edit service lets users swap backgrounds with AI-generated or uploaded images while adjusting lighting to match the subject. This new API provides a streamlined image editing solution and can serve e-commerce, real estate, photography, and creative projects.

Some of the things you can do include:

Background Replacement: Remove existing background and add new ones.
AI Background Generation: Create new backgrounds using AI generated images based on prompts.
Relighting: Adjust lighting in images that are under or overexposed.
Flexible Inputs: Use your own background image or generate one.
Lighting Adjustments: Modify light reference, direction, and strength.

Try it out

Grab your API key and head over to

How to use

Please invoke this endpoint with a POST request.

The headers of the request must include an API key in the authorization field. The body of the request must be multipart/form-data.

The body of the request should include:

subject_image
background_prompt and/or background_reference

The body may optionally include:

light_reference or light_source_direction
light_source_strength (requires light_reference or light_source_direction)
foreground_prompt
negative_prompt
preserve_original_subject
original_background_depth
keep_original_background
light_source_strength
seed
output_format

Note: for more details about these parameters please see the request schema below.

Results

After invoking this endpoint with the required parameters, use the id in the response to poll for results at the results/ endpoint. Rate-limiting or other errors may occur if you poll more than once every 10 seconds.

Credits

Flat rate of 8 credits per successful generation. You will not be charged for failed generations.

POST

v2beta

stable-image

edit

replace-background-and-relight

import requests

response = requests.post(
    f"https://api.stability.ai/v2beta/stable-image/edit/replace-background-and-relight",
    headers={
        "authorization": f"Bearer sk-MYAPIKEY",
        "accept": "image/*"
    },
    files={
        "subject_image": open("./husky-in-a-field.png", "rb")
    },
    data={
        "background_prompt": "cinematic lighting",
        "output_format": "webp",
    },
)

print("Generation ID:", response.json().get('id'))

{
  "id": "a6dc6c6e20acda010fe14d71f180658f2896ed9b4ec25aa99a6ff06c796987c4"
}

Authorizations

authorization

string

header

required

Use your Stability API key to authentication requests to this App.

Headers

authorization

string

required

Your Stability API key, used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.

Minimum string length: 1

content-type

string

required

The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.

Minimum string length: 1

Example:

"multipart/form-data"

stability-client-id

string

The name of your application, used to help us communicate app-specific debugging or moderation issues to you.

Maximum string length: 256

Example:

"my-awesome-app"

stability-client-user-id

string

A unique identifier for your end user. Used to help us communicate user-specific debugging or moderation issues to you. Feel free to obfuscate this value to protect user privacy.

Maximum string length: 256

Example:

"DiscordUser#9999"

stability-client-version

string

The version of your application, used to help us communicate version-specific debugging or moderation issues to you.

Maximum string length: 256

Example:

"1.2.1"

Body

multipart/form-data

subject_image

file

required

An image containing the subject that you wish to change background and relight.

Supported Formats:

jpeg
png
webp

Validation Rules:

Every side must be at least 64 pixels
Total pixel count must be between 4,096 and 9,437,184 pixels
The aspect ratio must be between 1:2.5 and 2.5:1

background_reference

file

An image whose style you wish to use in the background. Similar to the Control: Style API, stylistic elements from this image are added to the background.

Important: either background_reference or background_prompt must be provided.

Supported Formats:

jpeg
png
webp

Validation Rules:

Every side must be at least 64 pixels
Total pixel count must be between 4,096 and 9,437,184 pixels

background_prompt

string

What you wish to see in the background of the output image. This could be a description of the desired background scene, or just a description of the lighting if modifying the light source through light_source_direction or light_reference.

Important: either background_reference or background_prompt must be provided.

Maximum string length: 10000

foreground_prompt

string

Description of the subject. Use this to prevent elements of the background from bleeding into the subject. For example, if you find your subject is turning green with a forest in the background, try putting a short description of the subject in this field.

Maximum string length: 10000

negative_prompt

string

A blurb of text describing what you do not wish to see in the output image. This is an advanced feature.

Maximum string length: 10000

preserve_original_subject

number

default:0.6

How much to overlay the original subject to exactly match the original image. A 1.0 is an exact pixel match for the subject, and 0.0 is a close match but will have new lighting qualities. This is an advanced feature.

Required range: 0 <= x <= 1

original_background_depth

number

default:0.5

Controls the generated background to have the same depth as the original subject image. This is an advanced feature.

Required range: 0 <= x <= 1

keep_original_background

enum<string>

default:false

Whether to keep the background of the original image. When this is on, the background will have different lighting than the original image that changes based on the other parameters in this API.

Available options:

true,

false

light_source_direction

enum<string>

Direction of the light source.

Available options:

left,

right,

above,

below

light_reference

file

An image with the desired lighting. Lighter sections of the light_reference image will correspond to sections with brighter lighting in the output image.

Supported Formats:

jpeg
png
webp

Validation Rules:

Every side must be at least 64 pixels
Total pixel count must be between 4,096 and 9,437,184 pixels

light_source_strength

number

default:0.3

If using light_reference_image or light_source_direction, controls the strength of the light source. 1.0 is brighter and 0.0 is dimmer. This is an advanced feature.

Important: Use of this parameter requires light_reference or light_source_direction to be provided.

Required range: 0 <= x <= 1

seed

number

default:0

A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass 0 to use a random seed.)

Required range: 0 <= x <= 4294967294

output_format

enum<string>

default:png

Dictates the content-type of the generated image.

Available options:

jpeg,

png,

webp

Response

Replace Background and Relight was started.

string

required

The id of a generation, typically used for async generations, that can be used to check the status of the generation or retrieve the result.

Required string length: 64

Example:

"a6dc6c6e20acda010fe14d71f180658f2896ed9b4ec25aa99a6ff06c796987c4"