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