SAM3 Promptable Concept Segmentation

This Space provides both a UI and API for SAM3 inference with SAM2 compatibility. Use the interface below or call the API programmatically.

API Usage

1. Simple Text API (Gradio format)

import requests
import base64

# Encode your image to base64
with open("image.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# Make API request
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/predict",
    json={
        "data": [image_b64, "kitten", 0.5]
    }
)

result = response.json()
        

2. SAM2/SAM3 Compatible API (Inference Endpoint format)

import requests
import base64

# Encode your image to base64
with open("image.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# SAM3 Text Prompts Only
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/sam2_compatible",
    json={
        "inputs": {
            "image": image_b64,
            "text_prompts": ["kitten", "toy"],
            "confidence_threshold": 0.5
        }
    }
)

# SAM2 Compatible (Points/Boxes Only)
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/sam2_compatible",
    json={
        "inputs": {
            "image": image_b64,
            "boxes": [[100, 100, 200, 200]],
            "box_labels": [1],  # 1=positive, 0=negative
            "confidence_threshold": 0.5
        }
    }
)

# SAM3 with Multiple Text Prompts (processed individually)
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/sam2_compatible",
    json={
        "inputs": {
            "image": image_b64,
            "text_prompts": ["cat", "dog"],  # Each prompt processed separately
            "confidence_threshold": 0.5
        }
    }
)

# SAM3 Combined Visual Prompts (boxes + points in single call)
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/sam2_compatible",
    json={
        "inputs": {
            "image": image_b64,
            "boxes": [[50, 50, 150, 150]],  # Bounding box
            "box_labels": [0],  # 0=negative (exclude this area)
            "points": [[200, 200]],  # Point prompt
            "point_labels": [1],  # 1=positive point
            "confidence_threshold": 0.5
        }
    }
)

# SAM3 with Vectorize (returns both masks and polygons)
response = requests.post(
    "https://your-username-sam3-api.hf.space/api/sam2_compatible",
    json={
        "inputs": {
            "image": image_b64,
            "text_prompts": ["cat"],
            "confidence_threshold": 0.5,
            "vectorize": true,
            "simplify_epsilon": 2.0
        }
    }
)

result = response.json()
        

3. API Parameters

SAM2-Compatible API Input

{
  "inputs": {
    "image": "base64_encoded_image_string",

    // SAM3 NEW: Text-based prompts (each processed individually for best results)
    "text_prompts": ["person", "car"],  // List of text descriptions - each processed separately

    // SAM2 COMPATIBLE: Point-based prompts (can be combined with text/boxes)
    "points": [[x1, y1], [x2, y2]],  // Individual points (not nested arrays)
    "point_labels": [1, 0],  // Labels for each point (1=positive/foreground, 0=negative/background)

    // SAM2 COMPATIBLE: Bounding box prompts (can be combined with text/points)
    "boxes": [[x1, y1, x2, y2], [x3, y3, x4, y4]],  // Bounding boxes
    "box_labels": [1, 0],  // Labels for each box (1=positive, 0=negative/exclude)

    "multimask_output": false,  // Optional, defaults to False
    "confidence_threshold": 0.5,  // Optional, minimum confidence for returned masks
    "vectorize": false,  // Optional, return vector polygons instead of/in addition to bitmaps
    "simplify_epsilon": 2.0  // Optional, polygon simplification factor
  }
}
        

API Response

{
  "masks": ["base64_encoded_mask_1", "base64_encoded_mask_2"],
  "scores": [0.95, 0.87],
  "num_objects": 2,
  "sam_version": "3.0",
  "prompt_types": ["text", "visual"],  // Types of prompts used in the request
  "success": true,

  // If vectorize=true, additional fields:
  "polygons": [[[x1,y1],[x2,y2],...], [[x1,y1],...]],  // Array of polygon arrays for each object
  "polygon_format": "pixel_coordinates",
  "original_image_size": [width, height]
}