AI Cut: Basic
Point-based interactive segmentation. Upload a JPEG, then segment it using foreground (include) and background (exclude) point hints.
JPEG only. Both
input_key and output_key must end in .jpg or .jpeg.Note: Upload uses
multipart/form-data. Segment and get-public-url use application/json.Step 1 Upload
| Method | POST |
| Endpoint | /v3/file-ops/upload/ |
| Content-Type | multipart/form-data |
| Body | file + key |
| Returns | {"success": true} |
Step 2 Segment
| Method | POST |
| Endpoint | /v3/tools/ai/ai-cut/segment/ |
| Content-Type | application/json |
| Body | JSON with input_key, output_key, points |
| Returns | output_key |
import requests
API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Token {API_KEY}"}
INPUT_KEY = "my-project/photo.jpg" # AI Cut requires JPEG input
# Step 1 — Upload a JPEG image (AI Cut requires JPEG input and output)
with open("photo.jpg", "rb") as f:
upload_response = requests.post(
f"{API_BASE}/v3/file-ops/upload/",
headers=HEADERS,
files={"file": f},
data={"key": INPUT_KEY},
timeout=60
)
upload_response.raise_for_status()
print("Uploaded:", INPUT_KEY)
# 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_key": INPUT_KEY,
"output_key": "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_key"])
# 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_key": INPUT_KEY,
"output_key": "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_key"])
# Step 3 — Mint a public URL to access the result
pub = requests.post(
f"{API_BASE}/v3/file-ops/get-public-url/",
headers={**HEADERS, "Content-Type": "application/json"},
json={"key": refined["output_key"]},
timeout=10
)
pub.raise_for_status()
print("Download URL:", pub.json()["url"])Segment Request Body
| Field | Type | Required | Description |
|---|---|---|---|
input_key | string | Yes | Key of the source JPEG in your space. Must end in .jpg or .jpeg. |
output_key | string | Yes | Destination key for the result. Must end in .jpg or .jpeg. |
foreground_points | array | No | Points marking areas to include in the cutout. Each item: {"x": int, "y": int} in image pixels. Defaults to []. |
background_points | array | No | Points marking areas to exclude from the cutout. Same format as foreground_points. Defaults to []. |
Segment Response
{
"output_key": "my-project/segment-v1.jpg"
} | Field | Type | Description |
|---|---|---|
output_key | string | Key of the segmented result in your space. Call POST /v3/file-ops/get-public-url/ with this key to get a downloadable URL. |
Error Response
All errors return JSON with a detail field:
{
"detail": "input_key must be a JPEG file (.jpg / .jpeg)."
} | Status | Meaning |
|---|---|
400 | Bad request — non-JPEG key, missing fields, invalid point format, or malformed JSON |
401 | Missing or invalid Authorization header |
402 | Insufficient credits |
404 | File not found — input_key does not exist (expired, deleted, or wrong region) |
429 | Rate 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 key. Use different output keys per refinement (e.g.
segment-v1.jpg,segment-v2.jpg) to preserve each iteration, or overwrite the same key to save space. - Coordinates are in image pixels.
xandyare 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.