Edit background
Change a photo's background and lighting
You will need an API token to send HTTP requests. See Authentication for instructions.
Quick start
Firstly, you'll need to upload the image you want to process. These parameters must be supplied as multipart form data:
| Parameter | Example | Description |
|---|---|---|
file | @file.png | The image file as binary data. |
Please note that we only support the following formats: WEBP, JPEG and PNG. Note down this field from the response:
{
"image_id": "67762577...", // IMAGE_ID
}To understand how to use the image_id parameter, also see Image ID.
To generate environments (background and lighting), you will have to call the endpoint once for each keyword/prompt you want to use. Each one will generate a new picture.
This will start asynchronous processes that will be handled in the next step.
This is an example of request containing all required fields:
{
"id_image": "67762577...", // IMAGE_ID
"keyword": "{\"indoor_spaces\":\"Office\"}", // KEYWORD
"prompt": ""
}For more information on the usage of the keyword parameter, see Keywords.
Notification objects returned by this endpoint will inform you of the end of a generation on our servers. We recommend sending a request every 3 seconds at most, to not incur in rate limiting.
{
"name_list": ["edit_background"]
}After the process is complete, you might see a similar response:
{
"links": [{
"l": "https://..." // Download link
// ...
}]
}Where "l" points to a fully ready, modified version of the original image with the background and lighting changed to the keyword you specified in the previous step.
Uploading an image
Be careful!
All target images are deleted automatically after 24 hours of being uploaded. This action cannot be undone.
You can upload any image containing any subject (or no subject at all). Please note that we only support the following formats: WEBP, JPEG and PNG.
import json
import requests
api_url = "https://api.piktid.com/api"
access_token = "your_access_token"
target_path = "path_to_image"
with open(target_path, "rb") as target:
response = requests.post(
api_url + "/edit/target",
headers={"Authorization": "Bearer " + access_token},
files={
"file": target
},
).json()
image_id = response.get("id_image")Generating a new background
Our API can generate a single background with a single keyword at a time, but parallel processing is allowed and recommended. To generate multiple backgrounds, you just have to send multiple requests.
import json
import requests
api_url = "https://api.piktid.com/api"
access_token = "your_access_token"
image_id = "67762577..."
keywords = [
{"nature_landscapes": "Beach"},
{"outdoor_spaces": "Rooftop"}
]
options= {
"relight_strength": 1.0
}
for keyword in keywords:
data = requests.post(
api_url + "/edit/background",
headers={"Authorization": "Bearer " + access_token},
json={
"id_image": image_id,
"keyword": json.dumps(keyword),
"prompt": "",
"options": json.dumps(options)
},
).json()Generation options
The options parameter in the request body must be formatted as a JSON-encoded string. It can contain the following parameters:
| Parameter | Values | Description |
|---|---|---|
relight_strength | Number from 0.0 to 1.0 | Controls the amount of light/shadow generation on the main subject. A higher number will replace the lighting more and more, while zero will turn off the feature entirely. |
seed | Integer number | Seed used for random number generation. Two requests with the same seed will have the same result. If undefined, it will be randomized server-side. |
Keywords
A keyword defined as a single key-value pair, where:
- the key is a generic group (for example "special_occasions")
- the value is an expression of the key (for example "Christmas")
To better explain this concepts, here are the currently defined prompts as programming language type definitions:
from dataclasses import dataclass
from typing import Literal
@dataclass
class Prompt:
indoor_spaces: Literal[
"Studio",
"Living Room",
"Kitchen",
"Bathroom",
"Bedroom",
"Office",
"Cafe",
"Gym",
"Library",
]
outdoor_spaces: Literal[
"Street",
"Rooftop",
"Pool",
"Courtyard",
"Balcony",
"Skyscraper",
]
weather_effects: Literal[
"Rain",
"Fog",
"Sunset",
"Sunrise",
"Fire",
"Water",
"Snow",
]
nature_landscapes: Literal[
"Beach",
"Forest",
"Mountains",
"Desert",
"Lake",
"Garden",
"Tropical",
"Sky",
]
seasonal: Literal[
"Spring",
"Summer",
"Autumn",
"Winter",
]
special_occasions: Literal[
"Christmas",
"Halloween",
"Easter",
"Wedding",
"Birthday",
]
architectural: Literal[
"Modern",
"Industrial",
"Classic",
"Futuristic",
]
professional_business: Literal[
"Corporate",
"Medical",
"Conference",
]
transportation: Literal[
"Car",
"Airplane",
"Train",
]
materials_textures: Literal[
"Silk",
"Wood",
"Marble",
"Stone",
"Metal",
"Leather",
"Paper",
"Gold",
]
artistic_stylized: Literal[
"Paint",
"Graffiti",
"Abstract",
"Vintage",
"Minimalist",
]
colors_gradients: Literal[
"Solid",
"Gradients",
"Ombre",
]
entertainment: Literal[
"Cinema",
"Concert",
"Night",
]
florals: Literal[
"Roses",
"Lavender",
"Flowers",
"Leaves",
]type Prompt = Partial<{
indoor_spaces:
| "Studio"
| "Living Room"
| "Kitchen"
| "Bathroom"
| "Bedroom"
| "Office"
| "Cafe"
| "Gym"
| "Library"
outdoor_spaces:
| "Street"
| "Rooftop"
| "Pool"
| "Courtyard"
| "Balcony"
| "Skyscraper"
weather_effects:
| "Rain"
| "Fog"
| "Sunset"
| "Sunrise"
| "Fire"
| "Water"
| "Snow"
nature_landscapes:
| "Beach"
| "Forest"
| "Mountains"
| "Desert"
| "Lake"
| "Garden"
| "Tropical"
| "Sky"
seasonal:
| "Spring"
| "Summer"
| "Autumn"
| "Winter"
special_occasions:
| "Christmas"
| "Halloween"
| "Easter"
| "Wedding"
| "Birthday"
architectural:
| "Modern"
| "Industrial"
| "Classic"
| "Futuristic"
professional_business:
| "Corporate"
| "Medical"
| "Conference"
transportation:
| "Car"
| "Airplane"
| "Train"
materials_textures:
| "Silk"
| "Wood"
| "Marble"
| "Stone"
| "Metal"
| "Leather"
| "Paper"
| "Gold"
artistic_stylized:
| "Paint"
| "Graffiti"
| "Abstract"
| "Vintage"
| "Minimalist"
colors_gradients:
| "Solid"
| "Gradients"
| "Ombre"
entertainment:
| "Cinema"
| "Concert"
| "Night"
florals:
| "Roses"
| "Lavender"
| "Flowers"
| "Leaves"
}>In both languages, the following are valid keyword objects:
{
"architectural": "Modern",
}{
"weather_effects": "Rain",
}Waiting for results
Be careful!
Notifications are automatically deleted after exactly 10 minutes (600 seconds) from their creation.
Results are shared to clients via "notifications". Clients are expected to poll for notifications and handle them in the allowed time limit before they are automatically dismissed by the API.
import time
import requests
from pprint import pprint
api_url = "https://api.piktid.com/api"
access_token = "your_access_token"
image_id = "67762577..."
def process_notifications(response, image_id):
for notification in response.get("notifications_list", []):
if notification["name"] != "edit_background:
return None, None
if notification["data"]["address"] != image_id:
return None, None
return notification["data"], notification["id"]
return None, None
def delete_notification(notification_id):
requests.delete(
api_url + "/notification/delete_json",
headers={"Authorization": "Bearer " + access_token},
json={"id": notification_id},
)
count = 0
# Loops for 10 minutes, even though generation generally
# takes less time.
for _ in range(600):
response = requests.post(
api_url + "/notification_by_name_json",
headers={"Authorization": "Bearer " + access_token},
json={"name_list": "edit_background,error"},
).json()
data, notification_id = process_notifications(response, image_id)
if data is not None:
# Delete the notification to avoid reading it again
delete_notification(notification_id)
print(
f"Background generated! Keyword: {data['keyword']}"
)
link = data["links"][0]
# The "l" field contains a static link to the final image
print(link["l"])
count += 1
if count == len(keywords):
break
time.sleep(1)PRO users can also disable watermark application on the final image.