Keep your selection moving

About

A character walks past your title. A hand moves in front of a product. The thing you selected keeps moving, and its mask needs to move with it. SAM 3.1 video selection follows one chosen object through an original clip and returns its mask as a lossless MP4.

Name the visible object, click it, or mark it with a box on any frame. Tracking runs in both directions from that frame. Negative points and boxes help separate the chosen instance from its neighbours.

The mask keeps the original width, height, frame count and frame rate. White marks the selected object; black marks everything else. Use it in your compositor or editor for occlusion, selective effects and moving selections.

Call sam3_video_segment_fp16 from the JavaScript or Python SDK, or use --segment-video in the Creative Agent CLI. Upload a constant-frame-rate SDR source up to 30 seconds, 900 frames, 2560 pixels on either edge and 100 MB.

Prompting tips

Choose what is visible on the selected frame.

• Name the object — Use a short noun phrase such as "unicorn horn".
• Choose the frame — frameIndex is a zero-based source-frame index. The selection is tracked in both directions from it.
• Pick one instance — objectIndex chooses among matches ranked by score; zero is the strongest match. Use spatial prompts to distinguish lookalikes.

Use the mask in your edit

The highlighted horn is selected with text: "unicorn horn" on frame 127. Its mask follows the motion through the full clip.

Download the original lossless mask MP4 · Read the SDK and CLI guide

Pricing

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

Hard binary selection masks; fine hair and fur need a separate matting step.

SDR, square pixels and applied rotation are required. Text and points cannot be combined in one request.

One 1920 × 1080, 255-frame clip at 24 fps took 38.27 seconds end to end on an RTX 4090 in a single qualification run. Network and queue time vary.

API

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

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

const client = await SogniClient.createInstance({
  appId: 'video-selection-app',
  apiKey: process.env.SOGNI_API_KEY,
  network: 'fast'
});
const project = await client.projects.create({
  type: 'video', modelId: SAM3_VIDEO_SEGMENT_MODEL_ID,
  positivePrompt: '', numberOfMedia: 1,
  referenceVideo: readFileSync('clip.mp4'),
  sam3VideoPrompt: { text: 'unicorn horn', frameIndex: 127 }
});
console.log(await project.waitForCompletion());
client.disconnect();

# sam3_video_segment_fp16 is addressable by id via the JavaScript SDK (see the JavaScript tab).
# The REST workflow API routes this family through its flagship alias instead:

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -d '{
    "input": {
      "title": "First render",
      "steps": [{
        "id": "step1",
        "toolName": "generate_video",
        "arguments": { "prompt": "a slothicorn surfing a wave of liquid paint, slow push-in, cinematic", "duration": 5 }
      }]
    },
    "confirm_cost": true
  }'

Use the JavaScript or Python SDK, or sogni-agent --segment-video clip.mp4 --segment-text "unicorn horn" --segment-frame 127 -o mask.mp4. Full reference at docs.sogni.ai.