MetaSeg: Segment Anything packaged for pip, video and cloud GPU

Two predictor classes, automatic and manual

MetaSeg is a packaged version of the Segment Anything model, and the whole public surface is two classes imported from one module.

from metaseg import SegAutoMaskPredictor, SegManualMaskPredictor

SegAutoMaskPredictor is the automatic case, where the model decides what to segment on its own. SegManualMaskPredictor is the interactive case, where you give it points and boxes and it segments what you indicated.

The automatic path for an image:

# For image
results = SegAutoMaskPredictor().image_predict(
    source="image.jpg",
    model_type="vit_l", # vit_l, vit_h, vit_b
    points_per_side=16,
    points_per_batch=64,
    min_area=0,
    output_path="output.jpg",
    show=True,
    save=False,
)

The manual path takes the same shape plus your selections:

# For manuel box and point selection

# For image
results = SegManualMaskPredictor().image_predict(
    source="image.jpg",
    model_type="vit_l", # vit_l, vit_h, vit_b
    input_point=[[100, 100], [200, 200]],
    input_label=[0, 1],
    input_box=[100, 100, 200, 200], # or [[100, 100, 200, 200], [100, 100, 200, 200]]
    multimask_output=False,
    random_color=False,
    show=True,
    save=False,
)

The comment on the automatic example is the practical note for anyone running this on a modest GPU: if gpu memory is not enough, reduce the points_per_side and points_per_batch. The model_type choice is the other lever, with vit_l, vit_h and vit_b being the three variants.

The install is a single command:

pip install metaseg

The package is Apache-2.0, the primary language is Python, and the last push to the main branch was on 2026-10-19 with release v0.7.9 published on 2023-11-07.

Video prediction, and the parameters that change with it

The video path is the reason this package exists separately from the original model repository, because running a promptable segmentation model over a video is a different problem from running it over a still image.

# For video
results = SegAutoMaskPredictor().video_predict(
    source="video.mp4",
    model_type="vit_l", # vit_l, vit_h, vit_b
    points_per_side=16,
    points_per_batch=64,
    min_area=1000,
    output_path="output.mp4",
)

Two things differ from the image case. There is no show or save flag, because the result is written to the output path as a video. And min_area defaults to 1000 rather than 0, which is a filter that drops small regions, and on a video with many frames a low threshold produces a great deal of spurious output.

The manual video predictor takes a single set of points and labels rather than a list of lists:

# For video
results = SegManualMaskPredictor().video_predict(
    source="video.mp4",
    model_type="vit_l", # vit_l, vit_h, vit_b
    input_point=[0, 0, 100, 100],
    input_label=[0, 1],
    input_box=None,
    multimask_output=False,
    random_color=False,
    output_path="output.mp4",
)

The input_box is None here, so a video run is driven by points alone.

The examples/ directory mirrors the API surface with runnable scripts: image_cv_segautomask.py, image_sahi_slice_predict.py, image_segautomask.py, image_segmanualmask.py, video_segautomask.py and video_segmanualmask.py.

The extra features list adds the context. Support for Yolov5 and 8, Detectron2, Mmdetection and Torchvision models. Support for video and a web application through Hugging Face Spaces. Support for manual single, multi, box and point selection. Support for pip installation. Support for the SAHI library. And support for FalAI.

SAHI slicing, and using a detector to place the prompts

The SAHI integration is the most useful of the additions, because it solves a specific weakness in the underlying model.

SAHI is a library for sliced inference, which is how you run a detector over a large image by cutting it into overlapping tiles rather than resizing the whole thing down. Segment Anything is a promptable model, so it needs a prompt, and on a large image a single grid of prompt points misses objects. SAHI supplies the boxes: a detector finds candidate regions, and the segmenter then segments each one at full resolution.

pip install sahi metaseg

from metaseg.sahi_predict import SahiAutoSegmentation, sahi_sliced_predict

image_path = "image.jpg"
boxes = sahi_sliced_predict(
    image_path=image_path,
    detection_model_type="yolov5",  # yolov8, detectron2, mmdetection, torchvision
    detection_model_path="yolov5l6.pt",
    conf_th=0.25,
    image_size=1280,
    slice_height=256,
    slice_width=256,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)

SahiAutoSegmentation().image_predict(
    source=image_path,
    model_type="vit_b",
    input_box=boxes,
    multimask_output=False,
    random_color=False,
    show=True,
    save=False,
)

The parameters are the whole design. image_size is the size the image is scaled to for detection, slice_height and slice_width are the tile size, and the two overlap ratios control how much neighbouring tiles share, which is what stops an object on a tile boundary from being missed or segmented twice. detection_model_type names the detector, and the comment lists yolov8, detectron2, mmdetection and torchvision as the alternatives to yolov5.

Note that the detector and the segmenter have separate model_type arguments, and the example pairs a yolov5 detector with a vit_b segmenter, which is the sensible pairing given the memory cost of each.

The result of sahi_sliced_predict is a list of boxes, and those boxes are handed straight to the segmenter as input_box, so the two halves compose without any intermediate format.

FalAI, for when the GPU is not yours

The cloud route is offered for the case where you do not have the hardware locally, and it is the same API with a different transport.

pip install metaseg fal_serverless
fal-serverless auth login

The automatic mask path:

# For Auto Mask
from metaseg import falai_automask_image

image = falai_automask_image(
    image_path="image.jpg",
    model_type="vit_b",
    points_per_side=16,
    points_per_batch=32,
    min_area=0,
)
image.show() # Show image
image.save("output.jpg") # Save image

And the manual one:

# For Manual Mask
from metaseg import falai_manuelmask_image

image = falai_manualmask_image(
    image_path="image.jpg",
    model_type="vit_b",
    input_point=[[100, 100], [200, 200]],
    input_label=[0, 1],
    input_box=[100, 100, 200, 200], # or [[100, 100, 200, 200], [100, 100, 200, 200]],
    multimask_output=False,
    random_color=False,
)
image.show() # Show image
image.save("output.jpg") # Save image

Two things are worth noticing. The function names differ from the local ones, so the import line changes, and the parameter name is image_path where the local predictor uses source. The documentation also spells the manual function two ways, once in the import and once in the call, so check the spelling against the installed version rather than copying it from a page. The points_per_batch is 32 rather than 64, which is consistent with a remote call where the batch is a request parameter rather than a local memory constraint.

The return value is an image object with show and save methods rather than a results list, which is a different contract from the local predictors, and that difference is a reminder that the cloud path is a convenience wrapper rather than a drop-in replacement.

Packaging details, and what the version numbers mean

The pyproject.toml is a Poetry project, and it has a few details that matter when you install it.

The package name is metaseg and the version is 0.7.8, with the author and maintainer both listed as Kadir Nar. The Python constraint is >=3.8.1,<3.12.0, which means the package does not declare support for Python 3.12 or later, and that is worth checking against whatever you run in production. The classifiers confirm the range with Python 3.8, 3.9, 3.10 and 3.11 listed, and the operating system classifier is OS Independent.

The licence is Apache-2.0, and the development status classifier says Production/Stable.

The requirements.txt is generated with hashes for every pinned dependency, which is what a reproducible lock file looks like when it is produced by a tool that understands markers. The conditions on each line are tied to the Python version range, and the auth0-python and certifi and cffi entries all carry the same style of environment marker plus a hash, which is the secure-pip format.

The repository layout shows the packaging plus the project scaffolding: a metaseg/ package directory, examples/, scripts/, a requirements.txt and a requirements-dev.txt, a poetry.lock, pyproject.toml, a pre-commit.ci badge, a .pre-commit-config.yaml, a CODE_OF_CONDUCT.md and a LICENSE. The repository is named segment-anything-video and the homepage field points at it, while the package on PyPI is metaseg, and the README also points at a Hugging Face Space for a web application and at a pepy downloads badge.

The release tags tell a story of their own. v0.7.9 was published on 2023-11-07, v0.7.8 on 2023-06-29 and v0.7.6 on 2023-06-27, so the tagged releases stopped in 2023 while the branch has been pushed to far more recently, which usually means development continued on main without new tags being cut.

Editorial conclusion

Adopt MetaSeg when you want promptable segmentation from a pip install rather than a research checkout, because the two predictor classes cover the automatic and manual cases and the video path is already wired. Do not expect the model to be small, because the memory footprint is set by the ViT variant you pick and the point grid density you request. Before you run it, decide between the local and the FalAI route, since the cloud path needs an account and a different install, and check the Python range, because the package metadata declares support for 3.8.1 up to below 3.12.0.

Frequently asked questions

Official sources

1. Issues
2. kadirnar/segment-anything-video on GitHub
3. License: Apache-2.0
4. README
5. Releases