AI Cut: Basic

Point-based interactive segmentation. Upload a JPEG, then segment it using foreground (include) and background (exclude) point hints.

Step 1 Upload
MethodPOST
Endpoint/v3/file-ops/upload/
Content-Typemultipart/form-data
AuthToken YOUR_API_KEY
Bodyfiles + upload_path
Returnsfile_paths
Step 2 Segment
MethodPOST
Endpoint/v3/tools/ai/ai-cut/segment/
Content-Typeapplication/json
AuthToken YOUR_API_KEY
BodyJSON with input_file_path, output_file_path, points
Returnsoutput_file_path
import requests

API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Token {API_KEY}"}

# Step 1 — Upload a JPEG image (AI Cut requires JPEG input)
with open("photo.jpg", "rb") as f:
    upload_response = requests.post(
        f"{API_BASE}/v3/file-ops/upload/",
        headers=HEADERS,
        files={"files": f},
        data={"upload_path": "my-project"},
        timeout=60
    )

upload_response.raise_for_status()
input_file_path = upload_response.json()["file_paths"][0]
print("Uploaded:", input_file_path)

# Step 2 — Segment with point hints (application/json)
# foreground_points = areas to include, background_points = areas to exclude
segment_response = requests.post(
    f"{API_BASE}/v3/tools/ai/ai-cut/segment/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "input_file_path": input_file_path,
        "output_file_path": "my-project/segment-v1.jpg",  # must be JPEG
        "foreground_points": [{"x": 250, "y": 300}],
        "background_points": []
    },
    timeout=30
)

segment_response.raise_for_status()
result = segment_response.json()
print("Segmented:", result["output_file_path"])

# Refine — send updated points in a new request
# Always include ALL accumulated foreground and background points.
refine_response = requests.post(
    f"{API_BASE}/v3/tools/ai/ai-cut/segment/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "input_file_path": input_file_path,
        "output_file_path": "my-project/segment-v2.jpg",
        "foreground_points": [{"x": 250, "y": 300}, {"x": 270, "y": 320}],
        "background_points": [{"x": 50, "y": 50}]
    },
    timeout=30
)

refine_response.raise_for_status()
refined = refine_response.json()
print("Refined:", refined["output_file_path"])
Segment Request Body
FieldTypeRequiredDescription
input_file_pathstringYesPath of the source JPEG in your space. Must end in .jpg or .jpeg.
output_file_pathstringYesDestination path for the result. Must end in .jpg or .jpeg.
foreground_pointsarrayNoPoints marking areas to include in the cutout. Each item: {"x": int, "y": int} in image pixels. Defaults to [].
background_pointsarrayNoPoints marking areas to exclude from the cutout. Same format as foreground_points. Defaults to [].
Segment Response
{
    "output_file_path": "my-project/segment-v1.jpg"
}
FieldTypeDescription
output_file_pathstringPath of the segmented result in your space. Download via GET /v3/files/{path}.
Error Response

All errors return JSON with a detail field:

{
    "detail": "input_file_path must be a JPEG file (.jpg / .jpeg)."
}
StatusMeaning
400Bad request — non-JPEG path, missing fields, invalid point format, or malformed JSON
401Missing or invalid Authorization header
402Insufficient credits
404File not found — input_file_path does not exist
429Rate limit exceeded — slow down requests
Tips
  • Send one request at a time. Processing takes a few seconds. Buffer point additions on the client and send the next request only after the current one completes.
  • Send all accumulated points. Each segment call must include every foreground and background point placed so far, not just the latest ones. The model uses the full set.
  • Use a versioned output path. Use different output paths per refinement (e.g. segment-v1.jpg, segment-v2.jpg) to preserve each iteration, or overwrite the same path to save space.
  • Coordinates are in image pixels. x and y are measured from the top-left corner of the original image (not scaled or normalized).
  • JPEG only. Both input and output must be JPEG. If your source is PNG, convert it to JPEG before uploading.