Replace the background
This endpoint takes a photo and puts a different world behind the subject — a studio colour, a lifestyle scene, a seasonal backdrop — without touching the subject itself. It's the step after cut-out, built for teams who need the same product or portrait to live convincingly on ten different backgrounds.
Run it online
Run this on our servers with your account. Free tools run in your browser; this one bills your KIT balance per the price above.
The gap between a cut-out and a finished photo
Removing a background gets you a transparent subject, but a transparent subject isn't a finished photo — it's a half-done asset waiting for context. A shoe on nothing looks unfinished; a shoe on a warm gradient looks like a catalogue page. This endpoint closes that gap in one call: send the source photo, tell it what should replace the background, and get back a composited image where the subject sits naturally in its new setting.
Solid colour or generated scene
You can ask for a flat colour — pure white for marketplace compliance, a brand hex for a campaign, black for contrast — or describe a scene and let the task generate a plausible environment behind the subject: a kitchen counter, an outdoor patio, a soft studio backdrop with shadow. Either way the edge handling is the hard part, and it's what the task is tuned for: keeping the subject's boundary believable even where hair, fabric edges, or reflections would normally give away a bad composite.
Who actually reaches for this
Product teams use it to make one photoshoot serve five marketplaces, each with its own background rule. Real estate and listings platforms use it to neutralise distracting backdrops in user-submitted photos. Marketing teams reuse a single hero shot across a whole season of campaigns just by changing what's behind it, instead of rebooking a photographer for every backdrop.
Composite over cut-out, not instead of it
If all you need is transparency, the Remove Background endpoint alone is cheaper and simpler. This one is for the next step, when the transparent subject needs an actual home — a colour, a shadow, a sense of place — before it goes into a listing, an ad, or a print catalogue.
Fitting it into a pipeline
Because the task runs asynchronously, you submit the photo and background instruction, get a task_id immediately, and receive the finished composite through a signed webhook the moment it's ready — no polling, no blocking your upload flow. It slots naturally after an upload step and before a resize or watermark step, so a single photo can move through cut-out, background, and final formatting without ever leaving your pipeline.
What you can do with it
Marketplace-compliant listings
A seller's product photos are shot on a cluttered workbench; each one gets a pure white background applied before it's uploaded to a marketplace that requires it.
Seasonal campaign refresh
A single studio shot of a product gets a snowy backdrop for winter and a beach scene for summer, without booking a new photoshoot for either.
Real estate photo cleanup
A listing photo with a cluttered or distracting rear yard gets its background replaced with a neutral, tidy scene before publishing.
Consistent brand catalogue
A retailer standardises every supplier photo, regardless of original background, onto the same brand-colour backdrop across the entire catalogue.
FAQ
How do I replace an image background through the api?
POST to /image/replace-background with the source image and either a target colour or a scene description; you get a task_id back and the composited image arrives by webhook or signed link.
Can I use a flat colour instead of a generated scene?
Yes, you can specify a plain colour, including a specific brand hex, or describe a scene and let the task generate a believable environment instead.
Does it handle hair and fine edges well?
It's tuned to keep believable edges around the subject even where hair, fabric, or reflections make a clean composite hard, though extremely fine detail is best-effort.
Is there a free tier for the background replace api?
There's no free tier — free tiers get abused and slow everyone down. Access runs on a prepaid ForHosting KIT balance: top up from $10.00 (it never expires) and each request is charged at its published price, so a call with no balance returns HTTP 402. No subscription, no tokens, no invented credits, and a failed task is never charged.
How much does it cost to replace a background?
$0.062 per request plus $0.004 per image, and you're only charged for tasks that complete successfully.
Is the background replace api available now?
It's in deployment and not yet accepting jobs; the endpoint and pricing below are final and will go live shortly.
What's the difference between this and the background removal api?
Removal gives you a transparent cut-out; replacement goes one step further and composites the subject onto a new colour or scene in the same call.
Can I process many product photos at once?
Yes, pair this endpoint with the Batch Processing API to run background replacement across an entire catalogue, each image priced and metered separately.
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, and soon from our app, email and Telegram.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/image/replace-background \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://ejemplo.com/imagen.jpg"}'const res = await fetch("https://api.kit.forhosting.com/image/replace-background", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"image": "https://ejemplo.com/imagen.jpg"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/image/replace-background",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"image": "https://ejemplo.com/imagen.jpg"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/image/replace-background", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"image":"https://ejemplo.com/imagen.jpg"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"image":"https://ejemplo.com/imagen.jpg"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/image/replace-background", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"image": "https://ejemplo.com/imagen.jpg"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "image.replace_background",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
max_mb | 15 |
max_megapixels | 12 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |