API v1 · Python
Virtual staging API in Python
It's a plain REST API, so a few lines of Python and the requests library are all you need to stage, restage or upscale a photo from your own scripts.
Works with any Python 3 client · 1 credit per staged image
# Your key, from the API dashboard. Never commit it.
import os, requests
API = "https://app.pictastic.ai/api/v1"
KEY = os.environ["PICTASTIC_API_KEY"]
headers = {"Authorization": f"Bearer {KEY}"}
# 1. Free upload slot (costs no credits)
slot = requests.get(
f"{API}/presigned-urls", params={"count": 1}, headers=headers
).json()["uploads"][0]
# 2. PUT your photo to the slot
with open("empty-room.jpg", "rb") as f:
requests.put(slot["presignedUrl"], data=f,
headers={"Content-Type": "image/jpeg"})
# 3. Stage it (1 credit)
res = requests.post(f"{API}/virtual-staging", headers=headers, json={
"imageUrl": slot["publicUrl"],
"roomType": "Living Room",
"designStyle": "Modern",
}).json()
print(res["outputImageUrl"])Overview
How do I use the virtual staging API in Python?
You call the Pictastic virtual staging API from Python with any HTTP client such as requests: GET a free presigned upload URL, PUT your photo to it, then POST that URL to the /virtual-staging endpoint and read outputImageUrl from the JSON response. It is a plain REST API, so there is no SDK to install.
How it works
Upload, call, collect
Image inputs live on Pictastic storage, so every job starts with a free presigned upload.
- 1
Get a presigned upload URL
Ask for as many slots as you need, then PUT your image bytes straight to storage. This call is free — no credits.
- 2
Call the endpoint you want
Pass the returned publicUrl as imageUrl. Staging, removal and upscaling all take the same input shape.
- 3
Read the output URL
The response carries outputImageUrl and a downloadUrl, plus a jobId you can re-fetch later from the jobs history.
Why developers pick it
Built to drop into a Python codebase
Everything you need to wire staging into a Django, Flask or plain-script workflow.
No SDK to install
It is standard REST over HTTPS, so requests (or httpx, or urllib) is all you need. Nothing Pictastic-specific to pin in requirements.txt.
Bearer or x-api-key header
Send your key as an Authorization: Bearer header or x-api-key — whichever your existing client setup makes easier.
Synchronous JSON response
The staging POST returns outputImageUrl directly in the JSON, so a script reads the result inline without polling a queue.
1 credit, refunded on failure
You pay one credit per finished image and get it back automatically if a job fails — so a batch script never bills for errors.
Part of one API
Python is just one way to call the virtual staging API
It's a plain REST API, so the same endpoints work from any language. See the full API overview, or jump to a specific operation.
Virtual staging API in Python FAQ
How do I use the virtual staging API in Python?
You call the Pictastic virtual staging API from Python with any HTTP client such as requests: GET a free presigned upload URL, PUT your photo to it, then POST that URL to the /virtual-staging endpoint and read outputImageUrl from the JSON response. It is a plain REST API, so there is no SDK to install.
Which Python library should I use?
Any HTTP client works because it is a plain REST API. The example uses requests for readability; httpx or the standard-library urllib work identically. There is no Pictastic Python SDK to install.
How do I stage a whole folder of photos in Python?
Request several presigned upload URLs at once with the count parameter, then loop your folder, PUT each file to its slot and POST it to /virtual-staging. Each call returns its own jobId and outputImageUrl.
How much does it cost to call from Python?
The language makes no difference to price: staging and furniture removal are 1 credit per successful image and upscaling is 3 credits, drawn from the same balance, with presigned uploads free and failures refunded.
Stage your first photo from Python today
Create a key in the dashboard and the example above runs as-is once PICTASTIC_API_KEY is set.
Presigned uploads are free — you only spend credits on finished images.