samapi

A LitServe-based inference server for SAM2 and SAM3 medical image segmentation.

Getting Started

Install pixi:

curl -fsSL https://pixi.sh/install.sh | bash

Clone and install:

git clone https://github.com/hanayik/samapi.git
cd samapi
pixi install

Start the server (CPU inference, the default):

pixi run serve

Start the server with GPU inference (requires CUDA 12):

pixi run -e gpu serve

Run tests:

pixi run test

SAM3 Access (Optional)

SAM3 weights on Hugging Face are gated by Meta. To use SAM3, you must request access to the model at https://huggingface.co/facebook/sam3. Approval typically takes on the order of tens of minutes.

Once approved, create a Hugging Face access token at https://huggingface.co/settings/tokens and set it as the HF_TOKEN environment variable:

export HF_TOKEN=hf_...

When using Docker, pass it via a .env file or directly:

HF_TOKEN=hf_... docker compose up

The server works without SAM3 — if HF_TOKEN is not set or access has not been granted, SAM2 models will still load normally.

API

All requests go to POST /predict. Images are base64-encoded PNG/JPEG strings.

Point prompt (SAM2)

{
  "model": "sam2_l",
  "image": "<base64-encoded image>",
  "prompts": {
    "points": [[128, 128]],
    "point_labels": [1]
  },
  "session_id": "my-session"
}

Bounding box prompt (SAM2)

{
  "model": "sam2_l",
  "image": "<base64-encoded image>",
  "prompts": {
    "bbox": [50, 60, 100, 80]
  },
  "session_id": "my-session"
}

SAM3 request

{
  "model": "sam3",
  "image": "<base64-encoded image>",
  "prompts": {
    "points": [[128, 128]],
    "point_labels": [1]
  },
  "options": {
    "reset_prompts": true
  },
  "session_id": "my-session"
}

Response

Masks are returned as GeoJSON features:

{
  "masks": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[x1, y1], [x2, y2], ...]]
      },
      "properties": {
        "index": 0,
        "quality": 0.98,
        "model": "sam2_l"
      }
    }
  ]
}

Other endpoints

• GET /health — health check
• GET /models — list available models

Model Weights

Model weights are downloaded automatically on first use and cached locally in ~/.samapi (override with SAMAPI_ROOT_DIR).

SAM2

SAM2 weights are hosted by Meta on dl.fbaipublicfiles.com and downloaded directly over HTTPS. No authentication is required. Available models:

Model	Checkpoint
sam2_l	sam2_hiera_large.pt
sam2_bp	sam2_hiera_base_plus.pt
sam2_s	sam2_hiera_small.pt
sam2_t	sam2_hiera_tiny.pt

SAM3

SAM3 weights are hosted on Hugging Face (facebook/sam3) and downloaded via huggingface_hub. Access is gated — see SAM3 Access above for setup instructions. The HF_TOKEN environment variable must be set to a valid token with access granted.

Google Drive

The download system also supports Google Drive URLs (used by upstream dependencies). These are fetched using a bundled fork of gdown with cancellation support.

Caching

Once downloaded, weights are stored under ~/.samapi/<model_name>/ and reused on subsequent starts. To force a re-download, delete the corresponding directory.

References

• ksugar/samapi — the original project this repo was derived from