Replace background — drop any subject into any scene

Every team that ships visual content eventually hits the same wall: the subject is fine, the background is wrong, and the cutout looks like it was done with safety scissors. We built replace-background so a single API call gives you a Photoshop-grade alpha edge and a brand-new scene behind it — without a designer in the loop.

What it does

POST /v1/image/replace-background takes a source image and a scene prompt, and returns the same subject placed inside a freshly generated background. Two things happen inside the call, in order:

1. High-fidelity matting — we extract the subject with a clean alpha matte. Hair, fur, glass edges, fabric fringes, motion blur on a sleeve — the things that single-pass tools usually butcher. The output is a true alpha channel, not a hard binary mask with a feathered halo.
2. Scene generation — we generate a new background guided by your scene_prompt. Lighting direction, perspective, and depth are tuned so the subject sits inside the scene instead of floating on top of it.

The request body is intentionally small. Three fields, that's it:

• image_url — public URL of the source image. Required.
• scene_prompt — text description of the new background. Required.
• preserve_shadow — boolean, defaults to true. Keeps the cast shadow under the subject so the composite doesn't look weightless.

That's the entire surface area. No mask uploads, no separate matting step, no second call to inpainting, no need to hand the model a prior. Pass an image and a sentence; get a finished image back.

The endpoint is synchronous for normal-sized inputs and returns a URL to the rendered output. You can pull it down, re-upload to your own storage, or hand the URL straight to your frontend.

Why we built it

If you've tried solving this with a single diffusion pass, you already know the failure mode. The model imagines the subject and the scene together, which means it has license to redraw your product. The bottle gets a slightly different shape. The dress hem moves. The label drifts. For lifestyle imagery that's annoying. For an e-commerce catalogue, it's a lawsuit.

Most rivals have leaned into single-pass diffusion because it's easier to ship. The trade-off is that edge quality and subject fidelity both suffer, and you can't control them independently — when you crank up prompt adherence, the subject drifts more.

Our angle: separate the two problems.

• A purpose-built matting pipeline owns the subject. Its job is to lift the subject pixel-perfect, including the hard cases — translucent edges, wispy hair, soft shadows that should be kept and hard shadows that should be dropped.
• A guided generation stage owns the scene. It paints around an existing alpha matte rather than imagining a new one, so the subject is preserved bit-for-bit while the background is fresh.

The output is closer to a manual cutout-and-composite by a human retoucher than to a generative redraw. That difference matters the moment you're shipping at volume — when one bad frame in a hundred isn't a curiosity, it's a return.

We also run this on our own self-hosted infrastructure, which is why the per-call price is what it is. You're not paying a third-party generation provider's margin on top of ours.

Quickstart

Grab a key from the dashboard, then fire the call. Here's the curl version, verbatim:

curl -X POST https://api.pixelapi.dev/v1/image/replace-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/source.jpg", "scene_prompt": "modern kitchen counter with morning light"}'

Same thing in Python using requests:

import requests

resp = requests.post(
    "https://api.pixelapi.dev/v1/image/replace-background",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "image_url": "https://example.com/source.jpg",
        "scene_prompt": "modern kitchen counter with morning light",
        "preserve_shadow": True,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json())

A few practical notes for first-time integrators:

• The image_url has to be reachable from the public internet. If you're pulling from a private bucket, generate a short-lived signed URL and pass that.
• scene_prompt rewards specificity. "Kitchen" gives you a kitchen. "Modern kitchen counter with morning light, marble surface, soft window light from camera-left" gives you something you'd actually use. Direction of light is the single biggest lever — the subject's existing lighting will be matched against the scene, so prompts that name a light direction tend to composite cleaner.
• Leave preserve_shadow on for product photography. Turn it off if the source shadow is harsh or directional in a way that fights the new scene.
• Set a sane client timeout. Generation isn't free; treat the call like an LLM call, not a thumbnail resize.

If you want to batch, just fan out concurrently from your side — the endpoint is stateless per call. We don't need a batch envelope from you.

Use cases

Move studio product shots into lifestyle scenes — kitchen counter, beach, desk

Studio shots are cheap to produce and look exactly the same as everyone else's studio shots. The minute you drop the same bottle on a marble kitchen counter with morning light, or onto sand at golden hour, or onto a wood desk next to a notebook, it stops looking like a stock listing and starts looking like a brand. Teams that already have a clean catalogue on white can use replace-background to spin up an entire lifestyle library without re-shooting. The two-stage pipeline matters here because the product is the asset — if its silhouette shifts even a little, the customer notices on the PDP. Subject fidelity stays locked while the world around it changes.

Generate matrimony portrait backgrounds — temple, garden, festival lights

Indian matrimony and event photography lives or dies by the backdrop. The studio gives you a portrait against a paper backdrop; the family wants a temple, a garden, festival lights, a haveli courtyard. Until now that meant a Photoshop artist on payroll, or a markup on every print. With one API call per backdrop, a studio can offer the customer a menu of scenes for the same sitting and let them pick. The matting stage is what makes this work — saree pallus, fine jewellery, dupatta edges, baby hair on a forehead. Cheap matting eats those details. Ours doesn't, which is what lets you serve a discerning customer at a self-serve price.

Build A/B variants of one product across 10 backgrounds for ad testing

Performance marketers already know that creative is the variable that moves CPA, and that the only way to find the winning creative is to ship a lot of them. The blocker has always been production cost — a designer can't make ten backgrounds for a Tuesday afternoon test without becoming the bottleneck. Drive replace-background from your creative pipeline and the cost of the tenth variant drops to the same as the first. Run a Meta or Google ads test across ten scenes, kill the eight that lose, double down on the two that win, and rotate next week. The economics make experimentation actually cheap, not theoretically cheap.

Pricing

Flat per-call pricing, no monthly minimums, no per-resolution surcharges:

• 22 credits per call
• ₹0.015 per call
• $0.00018 per call

That price holds whether the source image is a phone snap or a 24-megapixel studio file, and whether your scene prompt is one word or three sentences. Credits are deducted on a successful render — failed calls don't bill. If you're running a creative test that needs ten variants per product across a thousand SKUs, you can do the math in your head and it'll come out to a number you can defend to finance.

There's no separate "premium quality" tier. The two-stage pipeline is what every call gets. We'd rather price one good thing flat than have you guess between three quality knobs.

Try it

• Get a key and start calling: https://pixelapi.dev/dashboard
• Full API reference, error codes, and field-by-field docs: https://pixelapi.dev/docs

If you're integrating into a catalogue pipeline, an ad-creative tool, or a matrimony product, this endpoint is the one to start with. Pull a real product image off your CDN, write a sentence, and run the curl above. If the first output isn't there yet, sharpen the scene_prompt — that's where 90% of the iteration happens. The pipeline does the rest.

Ship something. Then ship ten more.