Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

Pricing: $0.35/request. Endpoint: POST /v1/models/runflow/background-replace/runs.
Swap the background of any product photo for a new scene defined by a reference image and a short prompt. The model preserves the foreground subject while matching camera angle and lighting to the new background.

​
Overview

​
Pricing

  • Base price: $0.35/request
  • Note: Per image - background replace

​
Background Replace API

Endpoint: POST /v1/models/runflow/background-replace/runs

​
Run the model

​
Python

import requests

response = requests.post(
    "https://api.runflow.io/v1/models/runflow/background-replace/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
            "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
            "file_image": "image.webp",
            "file_reference": "reference.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)

​
Node.js

const response = await fetch(
  "https://api.runflow.io/v1/models/runflow/background-replace/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
            "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
            "file_image": "image.webp",
            "file_reference": "reference.webp"
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);

​
cURL

curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "Replace the white area on Image 1 with Image 2 as the background. Keep the perfume bottle perfectly intact and match the soft window light from Image 2.",
        "zip_url": "https://public.runflow.io/images/models/runflow/background-replace/examples/01-perfume-bottle-marble-counter/inputs.zip",
        "file_image": "image.webp",
        "file_reference": "reference.webp"
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON

​
Request parameters

ParameterTypeRequiredDescription
inputobjectrequiredModel input parameters. See “Input schema” below.
callback_urlstring | nulloptionalWebhook URL - POSTed when the run reaches a terminal state.
metadataobject | nulloptionalArbitrary key-value pairs attached to the run.

​
Input schema

FieldTypeRequiredAllowed valuesDescription
zip_urlfilerequiredAnyURL of a zip archive containing the foreground photo and the background reference image. Set file_image and file_reference to the filenames inside the zip.
file_imagestringrequiredAnyFilename of the foreground/product photo inside the zip (e.g. image.png). The model keeps this subject and replaces only the background.
file_referencestringrequiredAnyFilename of the background reference image inside the zip (e.g. reference.png). The model uses it as the new scene behind the foreground.
promptstringoptionalAnyOptional override for the scene description. Leave empty to use the default: replace the white area on Image 1 with Image 2 as the background, matching camera angle and lighting.

​
Output schema

FieldTypeDescription
image_urlsimage_listBackground-replaced image URLs.

​
Callback payload

When you provide a callback_url, Runflow POSTs to it once the run reaches a terminal state.
FieldTypeDescription
eventstringEvent type: “run.completed”, “run.failed”, or “run.cancelled”.
run_idstringThe unique identifier of the run.
statusstringTerminal status: “succeeded”, “failed”, or “cancelled”.
outputobject | nullThe run output. Null if the run failed or was cancelled.
duration_msnumber | nullTotal run duration in milliseconds.
created_atstring | nullISO 8601 timestamp when the run was created.
completed_atstring | nullISO 8601 timestamp when the run reached terminal state.
metadataobject | nullThe metadata object passed at run creation, if any.
  • Retries: 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
  • Headers: Runflow-Request-Id is always sent. Runflow-Signature is sent if a signing secret is configured.

​
Additional Resources

Browse all models

Browse the catalog.

Run lifecycle

Callbacks, polling, statuses.

Callbacks

Handle async results.

Pricing

How requests bill out.