Background & Object Manipulation API

These endpoints control backgrounds and objects in your images—remove backgrounds, replace scenes, insert new items, or clean up clutter with inpainting.

Introduction

Use the Background & Object APIs to automate e‑commerce cut‑outs, product recontext, creative edits, and high‑quality cleanup workflows.

Remove backgrounds for marketplaces and product catalogs.
Swap backgrounds while preserving the subject.
Insert or remove objects using masks or automatic detection.
Recontextualize product images into new environments.

Base URL

https://taiapi.aiphotocraft.com/

Authentication

All endpoints require your API key in the X-Api-Key header.

X-Api-Key: YOUR_API_KEY

Example

curl -X POST "https://taiapi.aiphotocraft.com/api/remove_bg" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@product.jpg;type=image/jpeg"

Recommended usage

Call these APIs from your backend, especially for high‑volume background processing or bulk object edits.

Background & Object Endpoints

Remove Background

POST/api/remove_bg

Remove the background from an image. Upload a single image and receive a version with the background removed.

Parameters

Name	Type	Required	Description
image	file (formData)	Required	Image to remove background from.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

import requests

url = "https://taiapi.aiphotocraft.com/api/remove_bg"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "accept": "application/json",
}

files = {
    "image": ("product.jpg", open("product.jpg", "rb"), "image/jpeg"),
}

response = requests.post(url, headers=headers, files=files)
print(response.status_code, response.text)

Replace Background

POST/api/replace_background

Replace or restyle the image background using Imagen BGSwap (EDIT_MODE_BGSwap). Upload a base image file, plus an optional mask image and a text prompt describing the desired new background.

Parameters

Name	Type	Required	Description
baseImage	file (formData)	Required	Base image (product or subject) whose background you want to change.
maskImage	file (formData)	Optional	Optional mask image isolating the subject (foreground).
prompt	string (formData)	Required	Text prompt describing the desired background, for example 'a light blue suitcase in an airport' or 'a clean white studio background'.
maskMode	string (formData)	Optional	Automatic mask mode when mask image is not provided. One of MASK_MODE_BACKGROUND, MASK_MODE_FOREGROUND, MASK_MODE_SEMANTIC. Defaults to MASK_MODE_FOREGROUND.
maskClasses	string (formData)	Optional	Comma-separated list of integer segmentation classes for MASK_MODE_SEMANTIC, for example "175,176" for bicycle and car.
maskDilation	number (formData)	Optional	Optional mask dilation as a fraction of image width. For tight product crops, 0.0 is recommended to avoid extending the foreground object.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

import requests

url = "https://taiapi.aiphotocraft.com/api/replace_background"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "accept": "application/json",
}

files = {
    "baseImage": ("base.jpg", open("base.jpg", "rb"), "image/jpeg"),
    # "maskImage": ("mask.png", open("mask.png", "rb"), "image/png"),  # optional
}

data = {
    "prompt": "a light blue suitcase in an airport",
    "maskMode": "MASK_MODE_FOREGROUND",
    "maskClasses": "175,176",
    "maskDilation": "0.0",
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.status_code, response.text)

Insert Objects

POST/api/insert_objects

Insert objects into an image using Imagen inpaint insertion (with or without mask). Upload a base image file, plus an optional mask image and a text prompt that describes what to insert.

Parameters

Name	Type	Required	Description
baseImage	file (formData)	Required	Base image file to edit.
maskImage	file (formData)	Optional	Optional mask image indicating where to insert objects.
prompt	string (formData)	Required	Text prompt describing what to insert in the masked or automatically detected region. For best results, describe the masked area and the object(s) to add.
maskMode	string (formData)	Optional	Automatic mask mode when mask image is not provided. One of MASK_MODE_BACKGROUND, MASK_MODE_FOREGROUND, MASK_MODE_SEMANTIC. Defaults to MASK_MODE_FOREGROUND.
maskClasses	string (formData)	Optional	Comma-separated list of integer segmentation classes for MASK_MODE_SEMANTIC (e.g. "175,176" for bicycle and car).
maskDilation	number (formData)	Optional	Optional mask dilation as a fraction of image width (e.g. 0.01).

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

import requests

url = "https://taiapi.aiphotocraft.com/api/insert_objects"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "accept": "application/json",
}

files = {
    "baseImage": ("base.jpg", open("base.jpg", "rb"), "image/jpeg"),
    # "maskImage": ("mask.png", open("mask.png", "rb"), "image/png"),  # optional
}

data = {
    "prompt": "insert a small white ceramic bowl with lemons on the table",
    "maskMode": "MASK_MODE_FOREGROUND",
    "maskClasses": "175,176",
    "maskDilation": "0.01",
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.status_code, response.text)

Remove Objects

POST/api/remove_objects

Remove objects from an image using Imagen inpaint removal (with or without mask). Upload a base image file, plus an optional mask image and a text prompt that describes what to remove.

Parameters

Name	Type	Required	Description
baseImage	file (formData)	Required	Base image file to edit.
maskImage	file (formData)	Optional	Optional mask image; white area will be edited/removed.
prompt	string (formData)	Required	Text prompt to guide removal (e.g. 'remove the person on the left').
maskMode	string (formData)	Optional	Automatic mask mode when mask image is not provided. One of MASK_MODE_BACKGROUND, MASK_MODE_FOREGROUND, MASK_MODE_SEMANTIC. Defaults to MASK_MODE_FOREGROUND.
maskClasses	string (formData)	Optional	Comma-separated list of integer segmentation classes for MASK_MODE_SEMANTIC (e.g. "175,176" for bicycle and car).
maskDilation	number (formData)	Optional	Optional mask dilation as a fraction of image width, for example 0.01.

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

import requests

url = "https://taiapi.aiphotocraft.com/api/remove_objects"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "accept": "application/json",
}

files = {
    "baseImage": ("base.jpg", open("base.jpg", "rb"), "image/jpeg"),
    # "maskImage": ("mask.png", open("mask.png", "rb"), "image/png"),  # optional
}

data = {
    "prompt": "remove the person on the left",
    "maskMode": "MASK_MODE_FOREGROUND",
    "maskClasses": "175,176",
    "maskDilation": "0.01",
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.status_code, response.text)

Product Recontext

POST/api/product_recontext

Recontextualize a product image into different scenes using Imagen Product Recontext. Upload a product image file and optionally control prompt, safety, watermark, sampling, and generation settings.

Parameters

Name	Type	Required	Description
image	file (formData)	Required	Product image file to recontextualize.
prompt	string (formData)	Optional	Optional prompt describing desired scene (for example 'on a wooden table in a cozy kitchen').
personGeneration	string (formData)	Optional	Controls people generation. One of 'allow_adult', 'allow_all', 'dont_allow'.
safetySetting	string (formData)	Optional	Safety filter threshold: 'block_low_and_above', 'block_medium_and_above', or 'block_only_high'.
addWatermark	boolean (formData)	Optional	Whether to add a digital watermark (default true).
sampleCount	integer (formData)	Optional	Number of images to generate (1–4). Only the first is returned by this API.
enhancePrompt	boolean (formData)	Optional	Whether to let the model enhance the prompt (default true).

Task Status Endpoint

GET/api/task-status/{task_id}

Get the status of a task and retrieve the processed image URL.

Name	Type	Required	Description
task_id	string (path)	Required	The ID of the task to get the status for.

Example Request

curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"

Example Response

{
  "image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}

Response Status Codes

Status Code	Description
200	Successfully retrieved task status.
400	Bad request.
401	Unauthorized.

Examples

import requests

url = "https://taiapi.aiphotocraft.com/api/product_recontext"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "accept": "application/json",
}

files = {
    "image": ("product.jpg", open("product.jpg", "rb"), "image/jpeg"),
}

data = {
    "prompt": "on a wooden table in a cozy kitchen",
    "personGeneration": "allow_all",
    "safetySetting": "block_low_and_above",
    "addWatermark": "true",
    "sampleCount": "1",
    "enhancePrompt": "true",
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.status_code, response.text)