AI Cut: Basic
Point-based interactive segmentation. Initialize a session, then refine the selection with green (include) and red (exclude) dots — free and unlimited.
Note: The two steps use different content types. Initialize uses
multipart/form-data (file upload). Segment uses application/json (JSON body).Step 1 Initialize
| Method | POST |
| Endpoint | /v3/ai-cut/initialize/ |
| Content-Type | multipart/form-data |
| Auth | Bearer YOUR_API_KEY |
| Body | Form field: image (file) |
| Returns | unique_filename |
| Cost | 1 credit |
Step 2 Segment
| Method | POST |
| Endpoint | /v3/ai-cut/segment/ |
| Content-Type | application/json |
| Auth | Bearer YOUR_API_KEY |
| Body | JSON with unique_filename, dots, request_number |
| Returns | output_url |
| Cost | FREE, unlimited per session |
import requests
API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# Step 1 — Initialize session (multipart/form-data)
# Uploads the image and prepares it for interactive segmentation.
with open("photo.jpg", "rb") as f:
init_response = requests.post(
f"{API_BASE}/v3/ai-cut/initialize/",
headers=HEADERS,
files={"image": f},
timeout=300
)
init_response.raise_for_status()
unique_filename = init_response.json()["unique_filename"]
print("Session:", unique_filename)
# Step 2 — Segment with points (application/json, FREE, unlimited)
# Green dots mark areas to include. Red dots mark areas to exclude.
# Always send ALL points accumulated so far, not just new ones.
segment_response = requests.post(
f"{API_BASE}/v3/ai-cut/segment/",
headers={**HEADERS, "Content-Type": "application/json"},
json={
"unique_filename": unique_filename,
"greenDots": [{"x": 250, "y": 300}],
"redDots": [],
"request_number": 1
},
timeout=300
)
segment_response.raise_for_status()
result = segment_response.json()
print("Segmented:", result["output_url"])
# Refine — add more points (still FREE, still unlimited)
# Include ALL previous points plus new ones.
refine_response = requests.post(
f"{API_BASE}/v3/ai-cut/segment/",
headers={**HEADERS, "Content-Type": "application/json"},
json={
"unique_filename": unique_filename,
"greenDots": [{"x": 250, "y": 300}, {"x": 270, "y": 320}],
"redDots": [{"x": 50, "y": 50}],
"request_number": 2 # increment with each call
},
timeout=300
)
refine_response.raise_for_status()
refined = refine_response.json()
print("Refined:", refined["output_url"])Initialize Response
{
"unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
} | Field | Type | Description |
|---|---|---|
unique_filename | string | Session identifier. Pass this in every /v3/ai-cut/segment/ call for this image. |
Segment Request Body
| Field | Type | Required | Description |
|---|---|---|---|
unique_filename | string | Yes | Session identifier returned by /v3/ai-cut/initialize/. |
greenDots | array | Yes | Points marking areas to include in the cutout. Each item: {"x": number, "y": number}. Coordinates are in image pixels. Include ALL dots from the session, not just new ones. |
redDots | array | Yes | Points marking areas to exclude from the cutout. Same format as greenDots. Pass an empty array if no exclusions. |
request_number | integer | Yes | Sequential counter starting at 1. Increment by 1 with each segment call in the session. Used to order concurrent requests correctly. |
Segment Response
{
"status": "completed",
"unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"output_url": "https://cdn.backgroundcut.co/.../result.png",
"request_number": 1
} | Field | Type | Description |
|---|---|---|
status | string | Processing status. "completed" when the cutout is ready. |
unique_filename | string | Session identifier, same as the request. |
output_url | string | URL to the segmented PNG image with transparent background. Temporary — download promptly. |
request_number | integer | Echoes the request_number from the request. Use this to match responses to requests if calling asynchronously. |
Error Response
All errors return JSON with a detail field:
{
"detail": "Session not found or has expired."
} | Status | Meaning |
|---|---|
400 | Bad request — missing fields, invalid point format, or malformed JSON |
401 | Missing or invalid Authorization header |
402 | Insufficient credits (charged on initialize, not segment) |
404 | Session not found — unique_filename has expired or never existed |
429 | Rate limit exceeded — slow down requests |
Tips
- Always send all accumulated points. Each segment call must include every green and red dot placed in the session so far, not just the latest ones. The model uses the full set to compute the segmentation.
- Segmentation is free after initialize. Credits are deducted once at initialization. All subsequent
/v3/ai-cut/segment/calls for the session are free. - Coordinates are in image pixels.
xandyare measured from the top-left corner of the original image (not scaled or normalized). - Output URLs are temporary — download the result as soon as the user confirms the selection.
- Sessions expire —
unique_filenamereferences are not permanent. Complete and download within a reasonable time after initialization.