Name: IC-Light Background API: Relight Photos to Match Scenes
Brand: magicapi
SKU: api-magicapi-background-relighting-api-zsxkib-ic-light-background
Availability: InStock
Author: API Market

Shashank Agarwal

# 💡 Subject Relighting API with a Background Image (zsxkib IC-Light Background)

## Overview
IC-Light Background, packaged by zsxkib, relights a subject photo so that it matches a background image and a text prompt. Send a `subject_image` (the foreground), a `background_image` that sets the lighting, and a `prompt` describing the result; the API returns the relit images. It can also compute normal maps.

Each request returns 1 to 12 images (`number_of_images`), plus extra normal map images when `compute_normal` is `true`.

## Features
- **Light from a background**: `light_source` `Use Background Image` (default) or `Use Flipped Background Image` takes the lighting from your background.
- **Fixed light directions**: `Left Light`, `Right Light`, `Top Light`, `Bottom Light` or `Ambient` instead of the background's lighting.
- **Prompt control**: `prompt` guides the relighting, `appended_prompt` (default `best quality`) is added to it, and `negative_prompt` lists what to avoid.
- **Sizes**: `width` and `height` from 256 to 1024 pixels in steps of 64 (default 512 x 640), then `highres_scale` (1 to 3, default 1.5) scales the final output.
- **Normal maps**: `compute_normal` returns additional normal map images (slower).
- **Several results at once**: `number_of_images` from 1 to 12.
- **Output formats**: `webp` (default), `jpg`, `png`, with `output_quality` 0 to 100.

## Use Cases
1. **Product and portrait compositing**: place a person or product into a new scene with lighting that matches it.
2. **Creative lighting**: try neon, sunset or studio light on the same subject photo.
3. **Marketing visuals**: make a set of on-brand images from one subject shot and several backgrounds.
4. **3D and design work**: use `compute_normal` to get normal maps of the subject.

## Visual Examples
### Example Input
Subject image:

![Subject photo of a woman sent as subject_image](https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-api-market.jpg)

Background image:

![Background image that sets the lighting](https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-2-api-market.webp)

Prompt: "Woman, detailed face, sci-fi RGB glowing, cyberpunk"

Settings: `light_source` `Use Background Image`, `width` `512`, `height` `832`, `steps` `25`, `cfg` `2`, `highres_scale` `1.5`, `highres_denoise` `0.5`, `number_of_images` `1`, `compute_normal` `false`, `output_format` `webp`, `output_quality` `80`, `appended_prompt` `best quality`, `negative_prompt` `lowres, bad anatomy, bad hands, cropped, worst quality`.

### Example Output
![The woman relit with the glowing cyberpunk lighting of the background](https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-output-t7fkjd86-api-market.webp)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `subject_image` | string (URL) | Yes |  |  | The main foreground image to be relit |
| `background_image` | string (URL) | Yes |  |  | The background image used to relight the foreground image |
| `prompt` | string | Yes |  |  | A text description guiding the relighting and generation process |
| `appended_prompt` | string | No | `best quality` |  | Additional text appended to the main prompt |
| `negative_prompt` | string | No | `lowres, bad anatomy, bad hands, cropped, worst quality` |  | A text description of attributes to avoid in the generated images |
| `compute_normal` | boolean | No | `false` |  | Whether to compute normal maps (slower, but provides additional output images) |
| `width` | integer | No | `512` | `256`, `320`, `384`, `448`, `512`, `576`, `640`, `704`, `768`, `832`, `896`, `960`, `1024` | Width of the generated images in pixels |
| `height` | integer | No | `640` | `256`, `320`, `384`, `448`, `512`, `576`, `640`, `704`, `768`, `832`, `896`, `960`, `1024` | Height of the generated images in pixels |
| `steps` | integer | No | `25` | 1 to 100 | Number of diffusion steps (more steps generally improve quality but increase processing time) |
| `cfg` | number | No | `2` | 1 to 32 | Classifier-free guidance scale: higher values follow the prompt more closely, lower values allow more creative interpretation |
| `highres_scale` | number | No | `1.5` | 1 to 3 | Multiplier for the final output resolution relative to the initial latent resolution |
| `highres_denoise` | number | No | `0.5` | 0.1 to 1 | Denoising applied when refining the high-resolution output (higher keeps closer to the upscaled latent, lower adds more new detail) |
| `light_source` | string | No | `Use Background Image` | `Use Background Image`, `Use Flipped Background Image`, `Left Light`, `Right Light`, `Top Light`, `Bottom Light`, `Ambient` | Type and position of the lighting applied to the initial background latent |
| `seed` | integer | No | none |  | Fixed random seed for reproducible results (omit for a random seed) |
| `number_of_images` | integer | No | `1` | 1 to 12 | Number of unique images to generate from the same input and settings |
| `output_format` | string | No | `webp` | `webp`, `jpg`, `png` | Image file format of the output images |
| `output_quality` | integer | No | `80` | 0 to 100 | Compression quality for lossy formats (jpg and webp). 100 is best, 0 is lowest |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.043 per API unit.
- **1 API unit = 1 request with up to 39 seconds of processing.** A request that takes longer is billed one more unit for each started 39-second block (for example, 50 seconds of processing is 2 units, $0.086).
- More images (`number_of_images`), more `steps`, larger sizes, a higher `highres_scale` and `compute_normal` add processing time and can add units.
- The example request (1 image at 512 x 832, 25 steps) took 5.5 seconds of processing, so it was billed 1 unit ($0.043).
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/background-relighting-api-zsxkib-ic-light-background`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/background-relighting-api-zsxkib-ic-light-background/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "60015df78a8a795470da6494822982140d57b150b9ef14354e79302ff89f69e3",
    "input": {
      "cfg": 2,
      "steps": 25,
      "width": 512,
      "height": 832,
      "prompt": "Woman, detailed face, sci-fi RGB glowing, cyberpunk",
      "light_source": "Use Background Image",
      "highres_scale": 1.5,
      "output_format": "webp",
      "subject_image": "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-api-market.jpg",
      "compute_normal": false,
      "output_quality": 80,
      "appended_prompt": "best quality",
      "highres_denoise": 0.5,
      "negative_prompt": "lowres, bad anatomy, bad hands, cropped, worst quality",
      "background_image": "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-2-api-market.webp",
      "number_of_images": 1
    }
  }'
```

Response (201 Created):
```json
{
  "id": "t7fkjd869nrmw0d1d91amca3xr",
  "version": "60015df78a8a795470da6494822982140d57b150b9ef14354e79302ff89f69e3",
  "status": "starting",
  "created_at": "2026-10-23T19:34:34.469Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/background-relighting-api-zsxkib-ic-light-background/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "t7fkjd869nrmw0d1d91amca3xr",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-output-t7fkjd86-api-market.webp"
  ],
  "error": null,
  "created_at": "2026-10-23T19:34:34.469Z",
  "started_at": "2026-10-23T19:34:35.469Z",
  "completed_at": "2026-10-23T19:34:55.469Z"
}
```

`output` is an array of image URLs: one per generated image, plus the normal map images when `compute_normal` is `true`.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `background_image` or a `width` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why (for example, an image URL that cannot be downloaded). Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/background-relighting-api-zsxkib-ic-light-background";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "60015df78a8a795470da6494822982140d57b150b9ef14354e79302ff89f69e3", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  cfg: 2,
  steps: 25,
  width: 512,
  height: 832,
  prompt: "Woman, detailed face, sci-fi RGB glowing, cyberpunk",
  light_source: "Use Background Image",
  highres_scale: 1.5,
  output_format: "webp",
  subject_image: "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-api-market.jpg",
  compute_normal: false,
  output_quality: 80,
  appended_prompt: "best quality",
  highres_denoise: 0.5,
  negative_prompt: "lowres, bad anatomy, bad hands, cropped, worst quality",
  background_image: "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-2-api-market.webp",
  number_of_images: 1
}).then((output) => output.forEach((url) => console.log(url)));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/background-relighting-api-zsxkib-ic-light-background"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "60015df78a8a795470da6494822982140d57b150b9ef14354e79302ff89f69e3", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "cfg": 2,
    "steps": 25,
    "width": 512,
    "height": 832,
    "prompt": "Woman, detailed face, sci-fi RGB glowing, cyberpunk",
    "light_source": "Use Background Image",
    "highres_scale": 1.5,
    "output_format": "webp",
    "subject_image": "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-api-market.jpg",
    "compute_normal": False,
    "output_quality": 80,
    "appended_prompt": "best quality",
    "highres_denoise": 0.5,
    "negative_prompt": "lowres, bad anatomy, bad hands, cropped, worst quality",
    "background_image": "https://blog.api.market/wp-content/uploads/2026/10/ic-light-background-input-2-api-market.webp",
    "number_of_images": 1,
})
for url in output:
    print(url)
```

## FAQ
- **What is the difference between the subject and background images?**
  - `subject_image` is the photo that gets relit. `background_image` provides the lighting and scene the subject should match.
- **Can I relight without using the background's light?**
  - Yes. Set `light_source` to `Left Light`, `Right Light`, `Top Light`, `Bottom Light` or `Ambient`.
- **What size is the output?**
  - The base size is `width` x `height` (each 256 to 1024 in steps of 64), scaled by `highres_scale` (default 1.5).
- **How many images does one request return?**
  - `number_of_images` (1 to 12, default 1), plus normal map images when `compute_normal` is `true`. Billing is by processing time, so more images can add units.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Relight a person or product photo to match any background with IC-Light Background: light from the background or a fixed direction, 1 to 12 images per request.