Magic expand
Augment images by generating outside borders
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 these fields from the response:
{
"image_id": "67762577...", // IMAGE_ID
}To understand how to use the image_id parameter, see Image ID.
This is an example of request containing all required fields to expand a picture:
{
"id_image": "67762577...", // IMAGE_ID
"top": 100,
"bottom": 0,
"left": -25,
"right": 10,
}For more information about what the side numbers represent, see Side offsets
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": ["expand_generate"]
}After the process is complete, you might see a similar response:
{
"notifications_list": [
{
"data": {
"id_image": "67762577...", // IMAGE_ID
"links": [{
"l": "https://..." // Download link
// ...
}],
},
"name": "expand_generate",
},
]
}Where "l" points to a fully ready, modified version of the newly expanded/cropped image as you requested 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 that's at least 64 by 64 pixels and at most 4096 by 4096 pixels. 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 + "/expand/target",
headers={"Authorization": "Bearer " + access_token},
files={
"file": target
},
).json()
image_id = response.get("id_image")Expanding an image
import json
import requests
api_url = "https://api.piktid.com/api"
access_token = "your_access_token"
image_id = "67762577..."
offsets = {
"top": 100,
"bottom": 0,
"left": -25,
"right": 10,
}
requests.post(
api_url + "/edit/generate",
headers={"Authorization": "Bearer " + access_token},
json={
"id_image": image_id,
} | offsets,
)Side offsets
To control image expansion and cropping, side offsets must be provided in the request.
Each side will be:
- expanded by the given offset if the offset is a positive number
- cropped by the given offset if the offset is a negative number
As an example, the following offsets will be applied to an image that's 900 pixels wide and 600 pixels tall:
offsets = {
"top": 100,
"bottom": 0,
"left": -25,
"right": 10,
}The resulting image will be:
900(original) +100(top) +0(bottom) =1000pixels tall600(original) -25(left) +10(right) =585pixels wide
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"] != "expand_generate":
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},
)
# Loops for 10 minutes, even though generating people 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": "expand_generate,error",
"id_image": image_id,
# Task IDs (returned by /generate) can optionally be used to filter notifications
# "id_task": ["..."],
},
).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"Generation finished!")
link = data["links"][0]
# The "l" field contains a static link to the final image
print(link["l"])
break
time.sleep(1)PRO users can also disable watermark application on the final image.