SAM 3 object segmentation

About

SAM 3 selects things. You give it an image and say which object you want — "the red ceramic teapot" — and it hands that object back as a mask, or as the object itself cut out on a transparent background. It is Meta’s Segment Anything Model 3, run on Sogni as a utility workflow rather than a generator.

That distinction is the single most important thing to understand about it, and the thing people get wrong first. The prompt is not a description of an image you want made. It is a name for something already in the picture you supplied. "A beautiful teapot, studio lighting, 8k" is a prompt for an image model; "the teapot on the left" is a prompt for SAM 3.

What comes back is lossless and full size: a binary PNG mask at the source image’s own width and height, or — with applyMask — the source carrying that mask as its alpha channel, so the selection is a ready-to-use cut-out and the mask is still recoverable from it. Nothing is resampled, resized or re-rendered.

You can point at the thing you want three ways. A text prompt names a concept and SAM 3 finds every instance of it. Click points say "this, here", with negative points to push the selection off a neighbour. Boxes act as examples of the concept, and a negative box excludes one instance of a text-prompted concept — every dog in the photo except that one. A threshold decides how confident a match has to be, and maxInstances keeps only the strongest handful.

SAM 3 is deterministic. The same image with the same selection returns the same mask every time, so re-rolling a seed does nothing at all and there is no seed control to re-roll. A mask is also not a generated image: it cannot be upscaled, enhanced or restyled, because there is nothing there to invent.

Pricing is flat at $0.005 per request whatever the source size, and that is honest rather than generous: SAM 3’s encoder resizes internally to a fixed resolution, so a four-megapixel photo genuinely costs the same to segment as a small thumbnail. Charging by the megapixel would have been charging for work nobody does.

Select in the Sogni app by choosing SAM 3 and uploading an image, or call it by model id from the JavaScript or Python SDK. It runs on the Sogni Supernet, a decentralized network of creator GPUs, so the 3.45GB checkpoint stays on somebody else’s machine.

Prompting tips

Almost every disappointing SAM 3 result comes from writing an image-generator prompt. The prompt names something already in your picture, and SAM 3 hands that thing back:

• Name it, do not describe it — "the red ceramic teapot" works. "a beautiful teapot, studio lighting, 8k" does not. Adjectives only earn their place when they tell one object in the frame apart from another.
• It can only select what is there — SAM 3 never invents. If you name something the image does not contain, there is nothing to return — which is exactly why an empty result usually means the prompt, not the model.
• Click when words get ambiguous — A positive point is unambiguous where "the cup" is not. Add negative points to push the selection off a neighbouring object it keeps grabbing.
• Boxes are examples, not crops — A positive box shows SAM 3 an example of the thing you mean. A negative box excludes one instance of a text-prompted concept, so it needs a text prompt alongside it to make sense.
• Move the threshold before you rewrite — It defaults to 0.5. Lower it when a real match is being rejected; raise it when the selection is bleeding into things you did not ask for.
• Cap the instances — A text prompt returns every match above the threshold, merged into one mask. Set maxInstances to 1 when you want only the strongest match instead.

Three ways to point at what you want

Every request carries one source image and one bounded selection. Coordinates are normalized from 0 to 1, so they describe the original image whatever its size.

Text and point prompts cannot be combined in one request. Points accept at most one box, and a negative box requires a text prompt.

The rest of the request

Pricing

Use pay-as-you-go Spark packs for each render (1 Spark = $0.005), or choose a flat-rate Sogni plan for credit-free fair-use generation in the app.

One flat rate, any source size. Segmentation cost really is per-image rather than per-megapixel, because SAM 3 resizes to a fixed resolution inside its encoder before it looks at anything.

1 Spark = $0.005. Pay as you go with Spark packs, or select under fair use on a flat monthly Sogni plan.

API

One Sogni API key reaches every model on the Supernet — call SAM 3 with the exact model id.

import { readFileSync } from 'node:fs';
import { SogniClient } from '@sogni-ai/sogni-client';

const client = await SogniClient.createInstance({
  appId: crypto.randomUUID(),
  apiKey: process.env.SOGNI_API_KEY,
  network: 'fast',
});

const project = await client.projects.create({
  type: 'image',
  modelId: 'sam3_image_segment_bf16',
  positivePrompt: '',
  numberOfMedia: 1,
  startingImage: readFileSync('room.jpg'),
  sam3Prompt: {
    // Names the object to select — not a description of an image to make.
    text: 'the red ceramic teapot',
    applyMask: true, // RGBA cut-out instead of the bare mask
    maxInstances: 1, // strongest match only
  },
});

const [url] = await project.waitForCompletion();
console.log(url); // PNG at the source image's own size

import asyncio, os
from sogni_client import SogniClient

async def main():
    async with await SogniClient.create(
        api_key=os.environ["SOGNI_API_KEY"],
        app_id="sam3-example",
    ) as sogni:
        project = await sogni.projects.create(
            type="image",
            model_id="sam3_image_segment_bf16",
            positive_prompt="",
            number_of_media=1,
            starting_image="room.jpg",
            # The prompt names the object to select.
            sam3_prompt={
                "text": "the red ceramic teapot",
                "apply_mask": True,
                "max_instances": 1,
            },
        )
        for url in await project.wait_for_completion():
            print(url)  # PNG at the source image's own size

asyncio.run(main())

Call sam3_image_segment_bf16 with a source image and a bounded sam3Prompt. Segmentation is not a Creative Agent tool, so there is no REST workflow alias — use the JavaScript or Python SDK. Full reference at docs.sogni.ai.