Source: https://docs.sogni.ai/models/sam3/

# SAM 3 object selection

Sogni runs **SAM 3** image segmentation on the Sogni Supernet as a standalone job. Give it one original still and tell it what to select with click points, boxes, or a short text label. It returns one lossless PNG at the source's exact dimensions: a black-and-white mask (white is the selection) or, if you ask for it, the selection cut out on transparency.

SAM 3 selects; it does not generate. It never adds scene content, animates a subject, or preserves a person's identity from their name. Selection is deterministic for a given image and prompt, so changing the seed changes nothing.

## [#](https://docs.sogni.ai/models/sam3/#workflow-id)Workflow ID

| Task | Model ID | Inputs |
| --- | --- | --- |
| Object selection | `sam3_image_segment_bf16` | One original image (`startingImage`) and a selection prompt (`sam3Prompt`) |

## [#](https://docs.sogni.ai/models/sam3/#product-availability)Product availability

-   **[Sogni World](https://docs.sogni.ai/sogni-world/):** the first step of every new path, and **Select anything** inside the featured story worlds.
-   **Sogni API and SDKs:** the exact model ID above. `sam3Prompt` points, boxes, and text are available from JavaScript SDK 5.31.0; `applyMask`, `maxInstances`, and negative boxes from 5.34.0.
-   **[Sogni Creative Agent Skill](https://docs.sogni.ai/sogni-intelligence/creative-agent-skill/):** selects objects and cuts out subjects with the same model ID.

## [#](https://docs.sogni.ai/models/sam3/#selection-prompt)Selection prompt

Coordinates run from 0 to 1 against the **original** image, with the origin at the top left. If your interface shows the image smaller, normalize the click within the displayed image and leave the uploaded original unchanged. Never send a cropped preview as the source.

| Field | Values | Notes |
| --- | --- | --- |
| `points` | Up to 32 `{ x, y, label }` | `label` is `positive` (include) or `negative` (leave out). |
| `boxes` | Up to 16 `{ x0, y0, x1, y1, label? }` | Normalized corners with `x0 < x1` and `y0 < y1`. With `text`, a `negative` box excludes one instance ("every dog except this one"). |
| `text` | 1–240 characters | A noun phrase naming the object ("the red ceramic teapot"), not a description of a desired image. Selects every matching instance. |
| `threshold` | 0–1, default 0.5 | With points, the job fails if the best candidate scores below it; with text, it filters matches. |
| `multimask` | boolean, default `true` with points | Chooses among SAM's whole, part, and subpart candidates for one ambiguous click. Point prompts only. |
| `maxInstances` | 1–16 | Keeps only the highest-scoring selections. With text, `1` returns just the strongest match. |
| `applyMask` | boolean, default `false` | Returns the selection cut out of the source as an RGBA PNG instead of the bare mask. |

Rules the SDK enforces before submitting:

-   At least one point, box, or text prompt is required.
-   Text and points cannot be combined.
-   With points, you can add at most one box, and it cannot be negative.

A single point may select only part of an object, such as a lantern's flame or a car's window. For the complete object, add include points, use **negative** points on neighbors, or switch to a short `text` label with a box around the one you want. The box guides SAM; use the returned mask, not the box, for outlines and hit testing.

## [#](https://docs.sogni.ai/models/sam3/#source-requirements)Source requirements

-   One PNG, JPEG, or WebP original. The result always matches the source's dimensions; width, height, steps, and guidance are ignored.
-   Sogni World additionally requires each edge between 256 and 2560 pixels for paths.

## [#](https://docs.sogni.ai/models/sam3/#pricing)Pricing

SAM 3 is priced as one flat request, whatever the source size. Sogni shows the estimate before the job runs; call `projects.estimateCost()` for a live estimate in your own app.

## [#](https://docs.sogni.ai/models/sam3/#javascript-sdk-example)JavaScript SDK example

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

const sogni = await SogniClient.createInstance({ appId: 'my-app', network: 'fast' });
await sogni.account.login('username', 'password');

const project = await sogni.projects.create({
  type: 'image',
  network: 'fast',
  modelId: 'sam3_image_segment_bf16',
  positivePrompt: '',
  numberOfMedia: 1,
  startingImage: fs.readFileSync('./original.png'),
  sam3Prompt: {
    points: [
      { x: 0.45, y: 0.6, label: 'positive' }, // inside the object
      { x: 0.12, y: 0.1, label: 'negative' }  // leave the sky out
    ],
    threshold: 0.5
  },
  outputFormat: 'png'
});

const [maskUrl] = await project.waitForCompletion(); // PNG at the source size
```

The completed job also reports how many selections were detected and returned, and each selection's score, normalized box, coverage, and whether it was included. Use them to tell a confident selection from a marginal one, or to spot that a text prompt matched more instances than you expected.

## [#](https://docs.sogni.ai/models/sam3/#using-the-result)Using the result

-   Inspect the mask at full size before relying on it.
-   Keep the original still. Use the mask as a selection guide for an editing model that accepts it, such as a context image for Krea 2 Identity Edit. A guide does not guarantee that every pixel outside the selection stays fixed, so check the whole result.
-   Sogni World uses the mask as both the clickable outline in a scene and the guide for creating the next scene.