AI Cut: Basic

Point-based interactive segmentation. Initialize a session, then refine the selection with green (include) and red (exclude) dots — free and unlimited.

Step 1 Initialize
MethodPOST
Endpoint/v3/ai-cut/initialize/
Content-Typemultipart/form-data
AuthBearer YOUR_API_KEY
BodyForm field: image (file)
Returnsunique_filename
Cost1 credit
Step 2 Segment
MethodPOST
Endpoint/v3/ai-cut/segment/
Content-Typeapplication/json
AuthBearer YOUR_API_KEY
BodyJSON with unique_filename, dots, request_number
Returnsoutput_url
CostFREE, 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"
}
FieldTypeDescription
unique_filenamestringSession identifier. Pass this in every /v3/ai-cut/segment/ call for this image.
Segment Request Body
FieldTypeRequiredDescription
unique_filenamestringYesSession identifier returned by /v3/ai-cut/initialize/.
greenDotsarrayYesPoints 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.
redDotsarrayYesPoints marking areas to exclude from the cutout. Same format as greenDots. Pass an empty array if no exclusions.
request_numberintegerYesSequential 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
}
FieldTypeDescription
statusstringProcessing status. "completed" when the cutout is ready.
unique_filenamestringSession identifier, same as the request.
output_urlstringURL to the segmented PNG image with transparent background. Temporary — download promptly.
request_numberintegerEchoes 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."
}
StatusMeaning
400Bad request — missing fields, invalid point format, or malformed JSON
401Missing or invalid Authorization header
402Insufficient credits (charged on initialize, not segment)
404Session not found — unique_filename has expired or never existed
429Rate 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. x and y are 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 expireunique_filename references are not permanent. Complete and download within a reasonable time after initialization.